Catalisa.Building Blocks
Catálogo/Plataforma/Audit Trail

Audit Trail

Beta

Quem fez o quê, quando e o que mudou — para toda a plataforma, por organização

10
Endpoints
5
Entidades
0
Provedores
Tenant
Escopo
3008
Porta
2026-02
Desde

Cada empresa cliente sua consulta a própria trilha de auditoria por API — quem mexeu, no que mexeu, o que estava antes e o que ficou depois — sem você instrumentar log em cada serviço nem exportar planilha para o auditor.

Para quem é
  • Fintechs e instituições reguladas que precisam responder a auditoria sobre acesso e alteração de dado
  • Plataformas B2B que querem entregar trilha de auditoria como funcionalidade para as próprias empresas clientes
  • Times de segurança que hoje reconstroem "quem mudou isso" lendo log de aplicação em cinco serviços
Substitui
  • Consulta manual a log de aplicação espalhado por vários serviços para reconstruir um incidente
  • Tabela de histórico reimplementada dentro de cada building block
O que não é
  • Uma plataforma de observabilidade — não guarda métrica, trace nem log de aplicação
  • Um SIEM — não correlaciona, não alerta e não detecta ameaça
  • Um cofre WORM com selo temporal de terceiro — a trilha é à prova de EVIDÊNCIA (encadeada e ancorada), não à prova de escrita; ver §14
  • Uma captura automática de tudo — cada building block publica os eventos dele explicitamente
O que dá para fazer

11 endpoints em 6 recursos.

Explorar a API →
01

Resumo executivo

O Audit Trail guarda a resposta para a pergunta que sempre chega tarde: quem mexeu nisso? Ele recebe os eventos que os outros building blocks publicam — usuário criado, produto alterado, cliente excluído — e transforma cada um numa linha consultável com o autor, o recurso, o instante e o antes e o depois do que mudou. Cada empresa cliente lê a própria trilha, com o mesmo token que usa no resto da plataforma.

Na prática ele resolve o dia em que alguém pergunta "por que este produto está com a taxa errada desde terça?". Sem trilha, a resposta é uma escavação em log de aplicação de cinco serviços, que na maioria das vezes termina em "não dá para saber". Com trilha, é GET /audit-trail/api/v1/logs/resource/product/:id e a linha do tempo do registro aparece.

Desde 22/09/2026 ele também responde à pergunta seguinte, que é a que um auditor faz: como sei que essa linha não foi alterada depois? Cada linha nova entra numa corrente por organização — número de sequência, hash do conteúdo e hash da linha anterior —, GET /verify recalcula a corrente inteira e aponta a primeira sequência quebrada, e um trabalho periódico assina a cabeça da corrente e publica o carimbo como evento, que o webhooks-engine entrega ao cliente. A partir daí existe, do lado dele, uma prova que nós não conseguimos alterar. GET /export devolve a trilha em NDJSON com essa âncora, para verificação offline sem nos consultar.

Está em beta. As cinco tabelas, as dez rotas (nove de leitura, verificação e configuração, uma de ingestão para produtores externos), o consumidor de eventos, o encadeamento, as âncoras assinadas e o expurgo por retenção estão implementados e cobertos por testes. Uma coisa a saber antes de qualquer outra: o consumidor que popula a trilha é desligado por padrão (AUDIT_CONSUMER_ENABLED, padrão false). Desde 10/09/2026 os stacks de staging e de produção o ligam no serviço audit-trail; num ambiente montado à mão, sem a variável, as rotas de consulta funcionam e devolvem vazio. Detalhe na §13 e na §15.

flowchart LR
  BB["Building blocks<br/>IAM · Customers · Products · ..."] -->|"publicam evento de domínio"| ST(["Redis Stream<br/>iam-events"])
  ST -->|"consome, quando ligado"| AC["AuditConsumer"]
  AC -->|"grava uma linha"| DB[("PostgreSQL<br/>audit.audit_logs")]
  DB -->|"GET /logs — com o token da própria organização"| CL["Empresa cliente"]
  DB -->|"GET /verify · GET /export"| CL
  JOB["Trabalho de âncora<br/>de hora em hora, só se a cabeça andou"] -->|"assina a cabeça (Ed25519)"| AN[("audit.audit_anchors")]
  JOB -->|"publica audit.anchor.created"| WH["webhooks-engine → endpoint do cliente"]
  WH -->|"a cópia que fica FORA do nosso alcance"| CL
AtributoValor
Identificadoraudit-trail
CategoriaPlataforma
EscopoTenant (exige organizationId no token em todas as 10 rotas; a ingestão carimba a organização do token no evento; a corrente, as âncoras e a chave de assinatura são por organização)
Porta (standalone)3008
Path alias@audit-trail
Prefixo HTTP/audit-trail
Schema PostgreSQLaudit
StatusBeta
Depende dePostgreSQL, Redis (fluxo de eventos e trava do trabalho de âncora), IAM
PermissõesAUDIT_LOGS_READ, AUDIT_CONFIG_MANAGE

02

O problema

negócio

O cenário

Uma plataforma B2B cresce e passa a ter dez serviços e dezenas de empresas clientes. Um dia chega a pergunta: quem alterou o limite de crédito daquele cliente, e quando? Ou pior, ela chega de fora — de um auditor, de um cliente irritado ou de um regulador.

O que trava hoje

  • O log de aplicação não é trilha de auditoria. Ele foi escrito para depurar, não para responder. Tem o que o desenvolvedor achou útil naquele dia, some com a rotação de disco e não separa o que é de qual empresa cliente.
  • A resposta exige juntar cinco fontes. O serviço que fez a alteração, o que autenticou, o que notificou e o balanceador — cada um com formato e retenção diferentes. Reconstruir uma sequência é trabalho manual de horas.
  • Ninguém guarda o antes. Log registra "produto atualizado". O que estava lá antes, que é a informação que resolve a disputa, foi sobrescrito.
  • Cada serviço reimplementa histórico. Uma tabela *_history aqui, um campo updated_by ali, um gatilho de banco acolá. Nenhum é igual ao outro, e o que falta só aparece quando é preciso.
  • A trilha do cliente é problema seu. Se você vende plataforma para empresas, elas vão pedir a própria trilha de auditoria — e vão pedir com um contrato de fornecimento na mão. Construir isso por cima de log de infraestrutura é caro e frágil.

O custo de não resolver

Há uma exigência legal direta e curta. O art. 37 da LGPD diz, na íntegra:

Art. 37. O controlador e o operador devem manter registro das operações de tratamento de dados pessoais que realizarem, especialmente quando baseado no legítimo interesse.

Não é recomendação, é obrigação. E "está no log de aplicação, se ninguém tiver rodado a rotação" não é registro. A lei não fixa formato nem prazo de guarda — o art. 40 delega à autoridade nacional dispor sobre "o tempo de guarda dos registros", e enquanto isso não vem, o prazo é decisão sua.

Para instituição regulada, o prazo é nominal

Para instituição autorizada pelo BACEN a exigência é nominal e vem com prazo. A Resolução CMN 4.893/2021, art. 21, I, manda instituir mecanismos de acompanhamento e de controle incluindo "a definição de processos, testes e trilhas de auditoria"; e o art. 23, VIII, determina que os registros desses mecanismos fiquem à disposição do Banco Central pelo prazo de cinco anos. Para instituição de pagamento, que a 4.893 exclui, a exigência espelhada está na Resolução BCB 85/2021, nos mesmos artigos 21 e 23.

NormaArtigoO que mandaPrazo de guarda
LGPD (Lei 13.709/2018)art. 37Manter registro das operações de tratamento de dados pessoaisNão fixa — o art. 40 delega o tempo de guarda à autoridade nacional
Res. CMN 4.893/2021art. 21, IMecanismos de acompanhamento e controle, incluindo trilhas de auditoria—
Res. CMN 4.893/2021art. 23, VIIIRegistros desses mecanismos à disposição do Banco CentralCinco anos
Res. BCB 85/2021arts. 21 e 23Mesma exigência, para instituição de pagamentoCinco anos

Fora do regulatório, o custo é operacional e chega antes: sem trilha, todo incidente vira investigação, e toda investigação sem dado termina em suposição.


03

Proposta de valor

negócio
AntesDepois
"Quem alterou isso?" termina em suposiçãoGET /logs/resource/:tipo/:id devolve a linha do tempo
O antes foi sobrescritoO evento carrega changes.before e changes.after
Cinco fontes de log, cinco formatosUma tabela, um formato, um filtro
Trilha por empresa cliente é projetoCada organização lê a própria com o token que já tem
Retenção é o que sobrou no discoRetenção declarada por organização, com expurgo executável

A trilha é do cliente, não só sua. O organizationId vem do token, e a consulta só devolve o que pertence àquela organização. Isso permite entregar auditoria como funcionalidade do seu produto, não só como ferramenta interna.

O evento é de domínio. products.product.updated com changes.before.description e changes.after.description diz o que mudou em linguagem de negócio. Um log de infraestrutura diria que houve um UPDATE numa tabela.

Registrar não custa latência de quem escreve. O building block que gerou a mudança publica no fluxo Redis e segue. O Audit Trail consome depois, em processo separado, com nova tentativa em caso de falha.

sequenceDiagram
  autonumber
  actor U as Usuário
  participant BB as Products
  participant ST as Redis Stream iam-events
  participant AC as AuditConsumer
  participant PG as PostgreSQL audit_logs
  U->>BB: altera o produto
  BB->>BB: grava a alteração
  BB->>ST: XADD iam-events
  BB-->>U: 200 OK
  Note over U,BB: a resposta não espera a auditoria
  ST->>AC: XREADGROUP no grupo audit-trail-consumers
  AC->>PG: INSERT da linha da trilha

Segredo não entra na trilha. Antes de gravar, o serviço percorre changes e metadata recursivamente e substitui por [REDACTED] todo campo cujo nome contenha password, secret, token, apiKey, authorization e variações. A lista completa está na §14 — junto com o que ela não cobre.

A retenção é uma decisão declarada. Cada organização define de 1 a 3.650 dias. O padrão é 365. O expurgo apaga o que passou do prazo e devolve quantas linhas removeu.


04

Casos de uso reais

negócio

Caso 1 — A alteração de taxa ganha autor e horário Cenário ilustrativo

Contexto

Financeira de crédito com quatro produtos ativos e uma equipe de produto com cinco pessoas autorizadas a alterar parâmetro comercial.

A dor

Na terça-feira, a taxa de um produto apareceu diferente do que o comitê aprovou. Ninguém assumiu, e o log de aplicação registrava apenas Request error e alguns 200. A reconstrução consumiu dois dias e terminou sem conclusão — o que é pior que uma conclusão ruim, porque não gera ação.

A solução com o BB

O building block Products publica products.product.updated a cada alteração, com o productId e os campos alterados. O consumidor grava a linha com actorId, action: UPDATE, resourceType: product e o instante. A investigação vira uma chamada: GET /audit-trail/api/v1/logs/resource/product/{id}.

flowchart LR
  T["Alguém do time altera a taxa"] --> P["Products"]
  P -->|"products.product.updated<br/>productId e campos alterados"| ST(["iam-events"])
  ST --> AC["AuditConsumer"]
  AC --> L["Linha da trilha<br/>actorId · UPDATE · product · instante"]
  L --> Q["GET /audit-trail/api/v1/logs/resource/product/{id}"]
O resultado

A pergunta "quem alterou" passa a ter resposta em segundos. E o efeito preventivo é maior que o investigativo: alteração com autor registrado muda o comportamento de quem altera.

Caso 2 — O cliente final consulta a própria trilha Cenário ilustrativo

Contexto

Plataforma B2B que atende 60 empresas clientes na mesma instância. Três delas são instituições reguladas e exigem trilha de auditoria contratualmente.

A dor

A cada auditoria de cliente, o time de suporte extraía log manualmente, filtrava numa planilha e mandava por e-mail. Três dias de trabalho por pedido, com risco real de vazar linha de uma empresa no relatório de outra.

A solução com o BB

As três empresas recebem um usuário com a permissão AUDIT_LOGS_READ e consultam GET /audit-trail/api/v1/logs com filtros por autor, tipo de recurso, ação e período. O organizationId sai do token, então não existe caminho em que uma empresa enxergue a linha de outra.

flowchart LR
  TA["Token da Empresa A<br/>claim organizationId = A"] --> R["GET /audit-trail/api/v1/logs<br/>permissão AUDIT_LOGS_READ"]
  TB["Token da Empresa B<br/>claim organizationId = B"] --> R
  R --> W["where organizationId = claim assinado do token"]
  W --> LA["Só as linhas da Empresa A"]
  W --> LB["Só as linhas da Empresa B"]
O resultado

O pedido de auditoria deixa de passar pelo suporte. E a exportação manual — que era o vetor de vazamento — deixa de existir.

Caso 3 — A retenção deixa de ser "o que sobrou no disco" Cenário ilustrativo

Contexto

Operação com contratos de níveis diferentes: clientes enterprise exigem cinco anos de trilha, os demais não exigem nada.

A dor

A retenção era a rotação de log do servidor, igual para todo mundo, e ninguém sabia dizer quanto tempo de fato. Responder "vocês guardam por quanto tempo?" numa proposta era um chute com cara de compromisso.

A solução com o BB

PUT /audit-trail/api/v1/config/retention define de 1 a 3.650 dias por organização. GET /config mostra o valor vigente, com padrão de 365 dias quando nunca foi configurado. POST /cleanup executa o expurgo da organização e devolve quantas linhas foram removidas.

flowchart LR
  C["PUT /config/retention<br/>retentionDays entre 1 e 3.650"] --> G["GET /config<br/>valor vigente, padrão 365"]
  G --> X["POST /cleanup"]
  X --> D["DELETE físico das linhas<br/>com createdAt fora do prazo"]
  D --> N["deletedCount na resposta"]
  X -. "não há agendador chamando o job" .-> M["Alguém precisa executar — §15"]
O resultado

A retenção vira cláusula verificável em vez de estimativa. Com uma ressalva importante: o expurgo não roda sozinho — não há agendador chamando o job. Ele é executável por API e alguém precisa executar. Está na §15.

Caso 4 — A obrigação de registrar operações de tratamento é da lei Referência de mercado

Contexto

O art. 37 da Lei 13.709/2018 obriga controlador e operador a manter registro das operações de tratamento de dados pessoais. Para instituição autorizada pelo BACEN, a Resolução CMN 4.893/2021 exige "trilhas de auditoria" (art. 21, I) e cinco anos de guarda à disposição do Banco Central (art. 23, VIII).

A dor

No mercado, a maioria das empresas descobre que "registro das operações de tratamento" e "log de aplicação" não são a mesma coisa no dia em que precisa apresentar o registro. Log de aplicação não tem autor confiável, não tem o estado anterior, não separa por controlador, e some com a rotação. E há uma armadilha adicional: quando o titular exerce o direito de eliminação do art. 18, VI, apagar a trilha junto costuma ser o oposto do que a lei pede — o art. 16, I autoriza a conservação para cumprimento de obrigação legal ou regulatória, que é exatamente o caso dos cinco anos do BACEN.

A solução com o BB

É assim que a Catalisa endereça: cada operação sobre dado pessoal em building block que publica evento gera uma linha com autor, tipo de autor, recurso, instante e as diferenças. A separação por organização é estrutural. A retenção é declarada por organização e vai a 3.650 dias, o que cobre com folga os cinco anos exigidos — e permite manter a trilha separada da base operacional quando o titular pede eliminação do cadastro.

flowchart LR
  T["Titular pede eliminação — LGPD art. 18, VI"] --> D{"O dado está sob obrigação legal ou regulatória?"}
  D -->|"não"| E["Elimina o cadastro operacional"]
  D -->|"sim — art. 16, I"| K["Conserva a trilha pelo prazo<br/>cinco anos, Res. CMN 4.893/2021 art. 23, VIII"]
  K --> R["Retenção declarada por organização<br/>até 3.650 dias"]
  E --> R2["A trilha do tratamento permanece como registro do art. 37"]
O resultado

O registro passa a existir como dado consultável, com prazo declarado. A avaliação de suficiência continua sendo do encarregado e do jurídico de cada operação, e este documento não a substitui — em especial porque a ausência de imutabilidade forte (§14) é o ponto que um auditor rigoroso vai levantar.


05

Mercado e diferenciais

negócio

Panorama. "Audit log" nomeia três produtos diferentes, e a confusão entre eles é a origem da maioria das compras erradas.

flowchart TD
  A["Audit log nomeia três produtos diferentes"]
  A --> F1["1 · Auditoria de infraestrutura<br/>AWS CloudTrail"]
  A --> F2["2 · Observabilidade e SIEM<br/>Datadog · Splunk"]
  A --> F3["3 · Audit log como funcionalidade do seu produto<br/>WorkOS · Catalisa Audit Trail"]
  F1 --> D1["Audita a conta de nuvem, sem instrumentação"]
  F2 --> D2["Ingere, indexa, busca e correlaciona qualquer log"]
  F3 --> D3["A sua empresa cliente consulta a própria trilha"]

Família 1 — auditoria de infraestrutura

O primeiro é auditoria de infraestrutura: AWS CloudTrail é o exemplo canônico. Ele registra tudo que acontece na conta de nuvem, automaticamente e sem instrumentação, e é excelente nisso. Mas ele não sabe o que é um produto de crédito, e não tem noção de "empresa cliente do cliente".

Família 2 — observabilidade e SIEM

O segundo é observabilidade e SIEM: Datadog e Splunk. Eles ingerem, indexam e buscam qualquer log em volume, com poder de correlação que nenhum banco relacional alcança. O custo acompanha o volume, a operação exige time, e transformar essa base em uma trilha que a sua empresa cliente possa consultar sozinha é um projeto, não uma configuração.

Família 3 — audit log como funcionalidade do seu produto

O terceiro é audit log como funcionalidade do seu produto: WorkOS Audit Logs é o representante mais claro, e o único análogo de verdade desta lista. A documentação dele é explícita no ponto que importa — "all events are scoped to an Organization" — e o painel administrativo gera links que você envia ao seu cliente para ele consultar e exportar a própria trilha. É a mesma intenção do Audit Trail da Catalisa, com duas diferenças de origem: no WorkOS você emite cada evento por API, integrando mais um fornecedor, e o dado de compliance sai do seu domínio e do país.

Atenção. Vale dizer isso com todas as letras, porque é o eixo de decisão: CloudTrail, Datadog e Splunk auditam a sua infraestrutura; WorkOS e o Audit Trail auditam o seu produto para os seus clientes. Comparar os cinco na mesma linha é o erro que produz compra errada.

Tabela comparativa

CritérioCatalisa Audit TrailWorkOS Audit LogsAWS CloudTrailDatadog Audit TrailSplunk
O que auditaDomínio dos seus building blocksEventos que você emiteChamadas de API da conta AWSRequisições ao próprio Datadog e log enviadoQualquer log ingerido
Trilha exposta ao seu cliente finalSim, nativoSim, com portal e exportaçãoNãoNãoVocê constrói
Captura sem instrumentarNão — cada BB publica (§7)NãoSim, automáticaParcialNão
Antes e depois da mudançaSim, changesSim, se você enviarParâmetros da chamadaDepende do logDepende do log
Retenção por organizaçãoSim, 1 a 3.650 diasPor planoPor trilha, não por tenantPadrão de 90 diasPor índice
Imutabilidade forte (WORM, selo)Não (§14)Não localizadaCom bloqueio de objeto no S3Não localizadaCom complemento
Busca e correlaçãoFiltros e paginaçãoBusca no painelConsulta básica, ou via LakeBusca completaO melhor da amostra
Alerta e detecçãoNãoNãoVia EventBridgeSimSim
ExportaçãoNão (§15)SimSim, para S3SimSim
Dado fica no seu domínioSimNãoSimNãoDepende da implantação
Custo públicoPrecificação em definiçãoUS$ 125/mês por conexão SIEM; US$ 99/mês por 1 M de eventos retidosPrimeira cópia de eventos de gestão sem custo; US$ 2,00 por 100 mil eventos nas cópias adicionaisSem preço unitário próprio publicadoSem valor publicado

Preços consultados em 2026-08-16 nas páginas públicas de WorkOS e AWS CloudTrail. Datadog lista o Audit Trail dentro de Log Management sem preço unitário próprio, e Splunk não publica valor em página aberta — direciona a contato comercial. Onde escrevemos "não localizada", significa exatamente isso: não encontramos documentação pública, o que não equivale a afirmar que o recurso não exista. Valores variam por região, plano, volume e negociação — consulte a tabela vigente antes de qualquer comparação numérica.

Nossos diferenciais

  1. A trilha nasce multi-tenant e o dado não sai do seu domínio. O organizationId é claim assinado e entra na cláusula where de toda consulta. Entregar auditoria à sua empresa cliente é conceder uma permissão, não construir um produto — e sem enviar registro de compliance para um fornecedor fora do país, que é o custo escondido da alternativa mais parecida. Um SIEM chega ao mesmo lugar, mas passando por modelagem de índice, controle de acesso e uma interface que alguém precisa manter.
  2. O evento é de domínio porque a plataforma é a mesma. customers.person.updated existe porque o Customers o publica, com o changes já montado. Um fornecedor externo só chega a esse nível se você instrumentar cada serviço à mão — que é exatamente o trabalho que este building block dispensa.
  3. Registrar não entra no caminho crítico. O building block que mudou o dado publica no fluxo Redis e responde ao usuário. O consumidor grava depois, com reprocessamento de mensagem não confirmada. Auditoria síncrona é auditoria que, no dia de pico, alguém desliga.

Quando escolher o concorrente

Se o seu requisito éEscolhaPor quê
Auditar infraestrutura — quem abriu porta no grupo de segurança, quem assumiu qual papelAWS CloudTrailEle faz isso automaticamente, e este building block não faz nada disso
Detecção, correlação e alerta sobre a trilhaUm SIEM: Splunk ou DatadogO Audit Trail não substitui nenhum dos dois
Imutabilidade forte — armazenamento WORM, selo temporal, prova criptográfica de não adulteraçãoUma trilha em armazenamento com bloqueio de objetoO Audit Trail não atende hoje (§14 e §15)
O mesmo caso de uso, com a stack fora da CatalisaWorkOS Audit LogsEntrega com painel pronto e sem depender dos nossos building blocks

O Audit Trail ganha quando o problema é auditar o domínio dos building blocks que você já usa, e entregar essa trilha às suas empresas clientes.


06

Modelo de cobrança e ROI

negócio

Precificação em definição. O Audit Trail não tem preço fechado. Ele é infraestrutura transversal: faz sentido junto do conjunto de building blocks cujos eventos ele registra, não isolado. Não há valor a divulgar, e este documento não estima nenhum.

O que dispara custo

DriverPor quê
Eventos registrados por mêsÉ o volume de escrita e a base do armazenamento
Período de retenção contratadoCinco anos de trilha custam cinco vezes o armazenamento de um ano
Consultas à trilhaFiltro por período e por recurso em tabela grande é a operação cara

Comparação de custo

A Catalisa não tem preço definido para este building block, então qualquer tabela comparativa teria um lado vazio e nós não a inventamos. O que dá para oferecer é a única âncora pública da categoria, para orientar conversa:

FornecedorBase de cálculo públicaOrdem de grandeza
Catalisa Audit TrailPrecificação em definição—
WorkOS Audit LogsPor evento retido e por conexão SIEMUS$ 99/mês por 1 milhão de eventos retidos; US$ 125/mês por conexão SIEM
AWS CloudTrailPor evento registradoPrimeira cópia de eventos de gestão sem custo; US$ 2,00 por 100 mil eventos nas cópias adicionais
Datadog Audit TrailDentro de Log ManagementSem preço unitário próprio publicado
SplunkWorkload, ingestão ou entidadeSem valor publicado

Consulta em 2026-08-16 às páginas públicas de WorkOS e AWS CloudTrail. Os modelos são incomparáveis na origem — evento retido, evento registrado, GB ingerido e workload não convertem entre si —, então trate a tabela como referência de modelo, não de valor. Não estimamos custo mensal para nenhum cenário.

ROI

A conta tem três linhas, e nenhuma é licença.

LinhaO que se evitaTem número?
Tempo de investigaçãoHoras a dias de pessoas caras por cada pergunta "quem alterou o quê"Depende da frequência da sua operação
Atendimento a auditoriaExtração manual recorrente do suporte, e o vazamento que ela pode causarDepende do número de pedidos por cliente
Risco regulatórioDescumprimento do art. 37 da LGPDNão — sem estimativa defensável

A primeira é o tempo de investigação. Sem trilha, reconstruir "quem alterou o quê" custa de horas a dias de pessoas caras, e frequentemente termina sem conclusão. Com trilha, custa uma consulta. Multiplique pela frequência com que a sua operação faz essa pergunta — a maioria dos times subestima, porque parou de perguntar quando percebeu que não havia resposta.

A segunda é o atendimento a auditoria. Extração manual por pedido de cliente é trabalho recorrente do suporte e é um vetor de vazamento — a planilha filtrada errada. Entregar consulta por API elimina os dois.

A terceira é o risco regulatório. O art. 37 da LGPD exige registro das operações de tratamento. Não colocamos número nessa linha porque não existe estimativa defensável de sanção, e material comercial com número inventado sobre multa de LGPD é passivo, não argumento.


07

Arquitetura

Este é o building block em que a arquitetura importa mais que a lista de rotas. Ele tem três caminhos independentes: um de escrita, assíncrono, que os blocos alimentam pelo fluxo e que produtores externos alcançam por uma rota de ingestão (POST /events, que só publica no fluxo — não grava linha); um de leitura, síncrono, com nove rotas; e um de testemunho, periódico, que assina a cabeça da corrente e a entrega ao cliente como evento.

O caminho de escrita — assíncrono, sem HTTP

flowchart TD
  BBS["IAM · Customers · Products · Billing · File Storage · ...<br/>25 building blocks"]
  EP["EventPublisher.publish()<br/>campos: type · payload JSON · metadata JSON<br/>injeta traceId e spanId do contexto de rastreamento"]
  ST(["Redis Stream iam-events"])
  G1["grupo audit-trail-consumers<br/>AuditConsumer<br/>AUDIT_CONSUMER_ENABLED — PADRÃO false — §15"]
  G2["grupo webhook-consumers<br/>webhooks-engine"]
  DEC{"metadata.organizationId presente?"}
  DROP["confirma e DESCARTA<br/>a mensagem é reconhecida e nada é gravado"]
  SVC["AuditLogService.logEvent()<br/>maskSensitiveData() em changes e metadata → [REDACTED]"]
  CH["AuditChainRepository.append()<br/>UMA transação: trava da organização → sequência → hash → INSERT → cabeça"]
  DB[("PostgreSQL · schema audit · audit_logs")]

  BBS -->|"service.create(...).andThen(publicar evento)<br/>a publicação é EXPLÍCITA, escrita linha a linha em cada serviço"| EP
  EP -->|"XADD"| ST
  ST --> G1
  ST --> G2
  G1 -->|"parseEventPayload — deriva ação, tipo de recurso e autor"| DEC
  DEC -->|"não"| DROP
  DEC -->|"sim"| SVC
  SVC -->|"o mascaramento vem ANTES do hash: o hash cobre o que fica gravado"| CH
  CH --> DB

O encadeamento — como a sequência não abre buraco com duas réplicas

A sequência não pode sair de um MAX(sequence) + 1: duas réplicas leem 7 e as duas escrevem 8. A atribuição acontece dentro da transação que insere a linha, com três defesas em profundidade:

flowchart TD
  A["BEGIN"] --> B["pg_advisory_xact_lock(hashtext(organization_id))<br/>serializa TAMBÉM o nascimento da organização,<br/>quando a linha de cabeça ainda não existe"]
  B --> C["INSERT ... ON CONFLICT DO NOTHING na cabeça"]
  C --> D["SELECT sequence, hash FROM audit_chain_heads ... FOR UPDATE"]
  D --> E["sequence = cabeça + 1 · prevHash = hash da cabeça<br/>hash = sha256(JSON canônico dos campos persistidos)"]
  E --> F["INSERT em audit_logs"]
  F --> G["UPDATE da cabeça"]
  G --> H["COMMIT"]
  UNI["Índice único (organization_id, sequence)"] -.->|"uma corrida que escapasse das travas<br/>vira erro de banco, e a escrita é repetida"| F

O createdAt é carimbado pela aplicação, não pelo now() do banco, porque entra no hash e precisa ser conhecido antes do INSERT. Consequência honesta: com várias réplicas, created_at não é rigorosamente monótono em relação à sequência. A verificação nunca depende dele — quem ordena a corrente é a sequência.

O caminho de testemunho — a âncora assinada

O encadeamento sozinho não prova nada contra quem tem acesso de escrita ao banco: quem pode reescrever uma linha pode recalcular a corrente inteira. O que fecha essa brecha é a âncora.

flowchart LR
  JOB["AnchorJob · a cada AUDIT_ANCHOR_INTERVAL_MINUTES<br/>trava no Redis: réplicas não ancoram juntas"] --> Q{"cabeça > última âncora?"}
  Q -->|"não"| SKIP["nada a fazer — organização parada<br/>não gera webhook de hora em hora"]
  Q -->|"sim"| SG["assina organizationId|sequence|hash|createdAt|keyId<br/>Ed25519, chave da organização"]
  SG --> TB[("audit.audit_anchors")]
  SG --> EV["EventPublisher: audit.anchor.created"]
  EV --> WE["webhooks-engine"] --> CLI["endpoint do CLIENTE<br/>a cópia fora do nosso alcance"]
  EV -.->|"o consumidor da trilha IGNORA audit.anchor.*<br/>gravá-la moveria a cabeça e geraria outra âncora, para sempre"| X["descartado"]

A chave privada de cada organização fica cifrada com AUDIT_TRAIL_SIGNING_MASTER_KEY — a master key deste bloco, não emprestada de outro: quem a tem consegue forjar a prova de integridade da trilha inteira.

O caminho de leitura — síncrono, HTTP

flowchart LR
  CLI["Cliente"] -->|"Bearer JWT"| HN["Hono basePath /audit-trail"]
  HN --> R1["/api/v1/logs<br/>AUDIT_LOGS_READ"]
  HN --> R2["/api/v1/logs/resource/:t/:id<br/>AUDIT_LOGS_READ"]
  HN --> R3["/api/v1/config<br/>AUDIT_LOGS_READ"]
  HN --> R4["/api/v1/config/retention<br/>AUDIT_CONFIG_MANAGE"]
  HN --> R5["/api/v1/cleanup<br/>AUDIT_CONFIG_MANAGE"]
  HN --> R6["/api/v1/verify · /api/v1/export<br/>/api/v1/anchors · /api/v1/keys<br/>AUDIT_LOGS_READ"]
  R6 --> SV
  R1 --> SV["AuditLogService · AuditConfigService<br/>ChainVerifyService · ChainExportService<br/>AnchorService · RetentionCleanupJob"]
  R2 --> SV
  R3 --> SV
  R4 --> SV
  R5 --> SV
  SV --> PG[("PostgreSQL<br/>audit_logs · organization_audit_configs")]

Publicar, consumir, gravar — o caminho inteiro

O diagrama abaixo é a resposta detalhada para "como uma alteração de dado vira uma linha da trilha", com os comandos Redis reais e os dois pontos em que a mensagem pode não virar linha nenhuma.

sequenceDiagram
  autonumber
  actor U as Usuário
  participant BB as Products — building block emissor
  participant EP as EventPublisher
  participant ST as Redis Stream iam-events
  participant AC as AuditConsumer
  participant SV as AuditLogService
  participant PG as PostgreSQL audit.audit_logs

  U->>BB: PUT /products/api/v1/products/:id
  BB->>BB: grava a alteração no próprio schema
  BB->>EP: publish com type, payload e metadata
  EP->>EP: injeta traceId, spanId e traceFlags do contexto de rastreamento
  EP->>ST: XADD iam-events com os campos type, payload e metadata
  BB-->>U: 200 OK
  Note over U,BB: a resposta ao usuário não espera a auditoria

  loop consumeLoop, enquanto o consumidor estiver ligado
    AC->>ST: XPENDING — reivindica com XCLAIM o que está ocioso há mais de 30.000 ms
    AC->>ST: XREADGROUP grupo audit-trail-consumers, COUNT 10, BLOCK 5000
  end
  ST-->>AC: até 10 mensagens
  AC->>AC: parseEventPayload — ação, tipo de recurso, autor, resourceId e changes

  alt sem metadata.organizationId
    AC->>ST: XACK e descarta — nada é gravado
  else com organizationId
    AC->>SV: logEvent
    SV->>SV: maskSensitiveData em changes e metadata
    SV->>PG: INSERT em audit_logs
    alt gravação bem-sucedida
      AC->>ST: XACK
    else falha na gravação
      AC--)ST: sem XACK — a mensagem volta na varredura de pendências
    end
  end

Quem escreve na trilha — e isso é automático?

É a pergunta mais importante deste documento, e a resposta tem duas partes.

A publicação do evento é explícita. Não existe middleware, gatilho de banco nem interceptador do Prisma que audite sozinho. Cada serviço, em cada operação que quer auditar, chama EventPublisher.publish() com o tipo, a carga e a metadata. Contamos 25 dos 32 building blocks com serviços que publicam eventos, e cerca de 87 tipos de evento declarados no código. Uma operação para a qual ninguém escreveu a chamada de publicação não aparece na trilha, e não há como saber disso pela trilha — a ausência é silenciosa.

O consumo é automático, quando ligado. Do lado do Audit Trail não há nada a instrumentar: o AuditConsumer lê o fluxo iam-events inteiro, deriva ação e tipo de recurso do nome do evento e grava. Um building block novo que publique algo.recurso.created já aparece na trilha, sem mudar uma linha aqui.

Publicação, nos outros building blocksConsumo, aqui
É automático?Não — a chamada é escrita à mão em cada serviçoSim, desde que o consumidor esteja ligado
Cobertura atual25 dos 32 building blocks, cerca de 87 tipos de eventoTodo evento que chegar ao fluxo
Building block novoPrecisa escrever a publicação neleAparece sem alterar uma linha aqui
Falha silenciosa?Sim — operação não publicada não deixa rastroSim — evento sem organizationId é descartado

O que isso significa comercialmente, sem rodeio: o Audit Trail é uma garantia sobre os eventos que a plataforma publica, e não sobre tudo que acontece nela. Vender como "captura automática de tudo" é venda errada e não sobrevive a uma auditoria técnica. O texto correto é: cobre as operações de domínio que os building blocks publicam, com o antes e o depois, por organização.

Decisões não óbvias

  • O consumidor é desligado por padrão. AUDIT_CONSUMER_ENABLED tem padrão false no schema de configuração; desde 10/09/2026 os stacks de staging e de produção o definem como 'true' no serviço audit-trail. Além disso, ele só é iniciado pelo main.ts do modo standalone — em modo monolito, src/main.ts não chama startAuditConsumer(). A intenção original era que o processamento fosse opcional por ambiente; o efeito hoje é que a trilha não é populada em nenhum ambiente publicado. Ver §13 e §15.
  • Um fluxo Redis, dois grupos de consumidor. O Audit Trail e o Webhooks Engine leem o mesmo iam-events, cada um no próprio grupo. Ligar ou desligar um não afeta o outro, e cada um tem a própria posição de leitura.
  • Um segundo fluxo, só da trilha. O AuditConsumer lê também platform-operator-events, com o mesmo grupo (audit-trail-consumers, criado em 0). É onde o EventPublisher grava os eventos do operador da plataforma (lista em src/shared/lib/operator-events.ts, hoje baas.simulated-provider.* e bureaus.simulated-provider.*), para que nenhum consumidor de webhook os veja. A gravação na trilha é a mesma: organização do metadata, autor, recurso e ação pelo nome do evento. Não há redação na leitura (o mascaramento é na gravação, e a cadeia cobre o que foi gravado), então o que não pode ser lido pela organização alvo não é gravado nela: o MOTIVO de uma concessão sai em ….simulated-provider.grant.reason.recorded, com a organização do OPERADOR no metadata, e fica na trilha dela. Para conferir: redis-cli XLEN platform-operator-events e redis-cli XINFO GROUPS platform-operator-events (um grupo só).
    • Um laço e uma conexão por fluxo. Os dois não são lidos no mesmo XREADGROUP: o comando falha por inteiro (NOGROUP/NOPERM) se um dos fluxos estiver sem grupo, sem chave ou negado por ACL, e a trilha de todos os eventos pararia. Cada fluxo falha, espera (1 s, 2 s, 4 s… até 30 s; log em error na primeira falha e depois uma vez por minuto) e se recupera sozinho — em NOGROUP o grupo é recriado em 0 —, e o outro segue. Catraca em Redis real: tests/integration/audit-trail/operator-stream-recovery.redis.integration.test.ts.
    • A ordem entre os dois fluxos não é a de publicação. A corrente encadeia na ordem em que a trilha grava, e cada fluxo é lido por um laço próprio: a sequence de um ato de operador e a de um evento de negócio da mesma organização não dizem qual foi publicado primeiro. Para "a concessão veio antes da conta?", vale metadata.timestamp (o instante de quem publicou), não a sequence. A corrente e o verify não são afetados — dentro de cada fluxo a ordem é a do fluxo.
    • O grupo existir é o que o baas confere antes de aceitar conceder ou revogar o provedor simulado (src/baas/README.md §13). Por isso o audit-trail sobe antes do baas.
  • Sem deduplicação (pré-existente, vale para os dois fluxos). A trilha não deduplica por id de mensagem: se o processo cai depois de gravar a linha e antes do XACK, a mensagem é reprocessada e a linha duplica.
  • Mensagens mortas: audit-trail:dead-letter. A mensagem cuja gravação falha em 4 entregas (a leitura e 3 reentregas, cada uma depois de 30 s ociosa) é copiada para o fluxo audit-trail:dead-letter — os campos originais mais sourceStream, sourceId, deliveryCount, reason, errorCode (quando o erro tem código) e deadLetteredAt — e só então confirmada, com log em error (event NOT written to the trail). Até 12/10/2026 o log dizia "moving to dead letter" e o código só fazia XACK: o evento saía dos pendentes e nada guardava que ele não tinha sido gravado.
    • Toda falha conta tentativa, e nenhuma mensagem segura a fila. Linha recusada (reason: ROW_REJECTED, ex. errorCode: P2023), banco fora ou transação que não fechou (DATABASE_UNAVAILABLE, ex. P1001, P2028), mensagem ilegível (PROCESSING_ERROR): todas seguem o mesmo caminho, e a falha de uma não impede a passada de seguir para as outras nem a leitura das novas. O motivo serve para quem lê as mortas, não muda o que o consumidor faz. Consequência assumida: uma indisponibilidade do Postgres maior que ~2 minutos manda para as mortas o que chegou no período — e quem recupera é o reprocessamento (abaixo), que é idempotente. DATABASE_UNAVAILABLE não quer dizer "o banco inteiro caiu": uma trava presa na cabeça da corrente de uma organização aparece como P2028 do mesmo jeito, e é por isso que o consumidor não espera por ela.
    • A espera pela trava da corrente tem limite (AUDIT_CHAIN_LOCK_TIMEOUT_MS, padrão 5 000 ms, de 100 a 9 000). Toda gravação pede a trava da corrente da organização (a consultiva e o FOR UPDATE na cabeça). Se outra transação a segura — uma sessão esquecida aberta, um expurgo longo — a gravação esperava enquanto a trava durasse: o prazo de 20 s da transação do Prisma não cancela a instrução em espera (medido: bloqueada depois de 45 s). Como o consumidor grava uma mensagem por vez, a trilha de todas as organizações do fluxo parava, sem erro e sem morta. Agora a primeira instrução da transação é set_config('lock_timeout', …, true) (local à transação): estourado o limite, o Postgres devolve 55P03, a gravação falha com reason: CHAIN_LOCK_TIMEOUT, conta tentativa, na 4ª vai para as mortas — e as outras organizações seguem. O padrão saiu de medição (scripts/audit-trail/append-contention.ts): com 50, 200 e 1 000 gravações simultâneas da mesma organização a maior espera pela trava foi 0,36 s com 5 conexões, 0,47 s com 17 e 0,90 s com 90, sem nenhuma falha; 5 s é 5,5 vezes o pior caso medido, e duas esperas seguidas (10 s) cabem nos 20 s da transação. O limite é por espera de trava, não por instrução: uma consulta lenta que não espera trava não é cortada por ele.
      • Quem mais espera essa trava: o expurgo por retenção (prunePrefix), que agora tem o mesmo limite — estourou, o job registra o erro daquela organização e segue para a próxima (antes ficava parado nela); e o reprocessamento das mortas, que grava pelo mesmo caminho (a morta continua na lista como stillFailing). Quem não espera: POST /events (só publica no fluxo), o job de âncora e as rotas de leitura e de verificação (leem a cabeça sem travar).
      • A variável é só do bb-audit-trail. AUDIT_CHAIN_LOCK_TIMEOUT_MS é validada pelo esquema de env compartilhado (src/shared/config/env.ts), que todo bloco carrega ao subir: um valor fora da faixa (100 a 9 000, inteiro) derruba qualquer bloco que a tenha no ambiente, não só a trilha. Grave-a apenas no env do serviço audit-trail, nunca no env comum do template; sem a variável, vale o padrão.
      • O limite só encurta a NOSSA espera. Ele não solta a trava de ninguém: a organização dona da trava presa continua sem gravar (e acumulando mortas) até a sessão que a segura acabar. O que solta é o idle_in_transaction_session_timeout no usuário da aplicação (passo de ambiente, adiante).
      • Expurgo que desiste por trava só deixa log (Failed to prune audit logs, com lockTimeout: true, e a organização no resumo de erros da rodada). Não há alerta de "expurgo pulado N rodadas seguidas": uma organização cuja corrente esteja sempre ocupada na hora do job pode ficar sem expurgo sem ninguém ser avisado. Lacuna conhecida; o alerta é PR seguinte.
      • Expurgo que passa dos 20 s da transação falha no fim sem apagar nada (pré-existente, não é deste limite): o DELETE roda dentro da mesma transação interativa de 20 s, e ao estourar o prazo tudo é desfeito. Uma organização com muito a apagar de uma vez pode nunca concluir o expurgo.
      • Quem segura por muito tempo: o expurgo de uma organização com muito a apagar segura a trava dela durante o DELETE. Se passar de ~2 minutos, os eventos dessa organização que chegarem no período vão para as mortas (CHAIN_LOCK_TIMEOUT) e voltam pelo reprocessamento — antes, paravam a trilha de todas.
    • Organização que não é UUID vai para as mortas na 1ª entrega, com reason: INVALID_ORGANIZATION_ID (ver o item seguinte).
    • Retenção e teto. O fluxo guarda o corpo inteiro do evento (o mesmo que está no fluxo de origem, sem mascaramento — o mascaramento acontece na gravação). Não há prazo: uma morta fica até ser reprocessada ou descartada, ou até o teto de ~10 000 entradas (MAXLEN ~) aparar as mais antigas — delas resta o log em error. O teto apara sem avisar, então a cópia loga em warn quando a lista passa de 80 % dele (the dead-letter stream is above 80% of its cap). Ninguém consome o fluxo.
    • Uma cópia por mensagem. Se a cópia é feita e o XACK falha, a volta seguinte encontraria a mensagem pendente e copiaria de novo. Uma marca por mensagem (audit-trail:dead-letter:copied:<fluxo>:<id>) faz a segunda cópia não acontecer. As marcas não têm teto de quantidade próprio: o que as limita é o prazo de 7 dias de cada uma (uma por mensagem morta, poucos bytes).
    • Se a cópia falhar (ACL na chave nova), a mensagem é confirmada como antes e o log diz NOT copied — o fluxo nunca trava por causa das mortas.
    • Para a concessão do provedor simulado isso ainda significa que a rota pode ter respondido "confirmado" (evento gravado no fluxo, com leitor) e a linha de auditoria não existir — mas agora o evento está no fluxo de mortas, não só no log. Como reprocessar: "Descobrir por que um evento não apareceu na trilha", adiante. Além disso, o reprocessamento de pendentes só enxerga as do próprio nome de consumidor (audit-consumer-<pid>), como no webhooks-engine (§15 de lá).
  • organization_id, actor_id e resource_id são UUID — e quem garante é a gravação. AuditLogService.logEvent (o único caminho de escrita) trata as três colunas antes de mascarar e de calcular o hash:
    • UUID vai na forma canônica — minúsculas, 8-4-4-4-12. O Postgres guarda UUID em minúsculas seja como for, e o hash da linha cobre o texto: um id recebido como ABCDEF12-… gerava um hash e gravava outro, e o GET /verify respondia hash_mismatch. As outras grafias que a coluna aceita ({…}, 32 hexadecimais sem hífen, urn:uuid:…) são o mesmo UUID e são normalizadas do mesmo jeito.
    • Autor ou recurso de outra forma — um host, uma referência de provedor, um id cunhado por produtor externo — vai para o metadata, nas chaves reservadas _auditResourceRef / _auditActorRef, e a coluna fica nula. A linha sempre é gravada. O prefixo _audit do metadata é da trilha: o que o produtor mandar sob ele é descartado antes de a linha ser montada (a trilha lê essas chaves de volta — é por _auditSourceId que o reprocessamento sabe que uma morta já foi gravada); um resourceRef/actorRef próprio do produtor não é tocado. Id vazio ("") não é id: coluna nula e nenhuma referência.
    • Organização que não é UUID não tem trilha. O contrato do bloco é "sem tenant não há onde gravar" (o mesmo do evento sem metadata.organizationId), e gravar a linha na organização de outro alguém seria inventar um dono. A recusa é nomeada (INVALID_ORGANIZATION_ID), acontece na primeira entrega — tentar de novo não muda nada — e o evento vai para o fluxo de mortas com esse motivo, com log em error. O reprocessamento não a grava; ela fica lá como evidência até ser descartada.
    • Antes disso o banco recusava o INSERT (P2023), o consumidor tentava 4 vezes e descartava: foi assim que toda recusa de ligar/desligar host do aplicativo (banking.host.map|unmap.refused) se perdeu até 12/10/2026 — o recurso dela é um host.
    • Histórico de host se lê por filter[eventType] (banking.host.mapped, banking.host.unmapped, banking.host.map.refused, banking.host.unmap.refused). As linhas não têm resourceId (não aparecem em filter[resourceId] nem na linha do tempo por recurso, que exigem UUID), e as de mapped|unmapped gravadas antes desta versão ficaram com resourceType: banking e a organização como recurso — a trilha não reescreve linha; as novas saem com banking_app_host.
  • Evento sem metadata.organizationId é descartado. Sem tenant não há onde gravar, então o consumidor confirma a mensagem e segue. É a decisão que mantém o isolamento inviolável e, ao mesmo tempo, a causa mais provável de "publiquei o evento e ele não apareceu na trilha".
  • A ação é derivada do nome do evento, não declarada. O último segmento do tipo é traduzido: created vira CREATE, updated vira UPDATE, deleted vira DELETE, e assim por diante. Um evento com sufixo desconhecido cai no padrão ACCESS. Isso torna o consumidor genérico — building block novo entra sem alteração aqui — e o preço é que a nomenclatura do evento vira contrato implícito.
  • Para CREATE, a carga inteira vira o "depois". Para DELETE, vira o "antes". Quando o evento não traz changes, o consumidor sintetiza: criação grava changes.after com a carga toda, exclusão grava changes.before. É o que dá conteúdo útil à trilha sem exigir que cada serviço monte a diferença.
  • A gravação é síncrona dentro do consumidor, com nova tentativa. Se a gravação falhar, a mensagem não é confirmada e volta na varredura de pendências. Mensagem entregue mais de três vezes é confirmada e descartada — o código chama isso de fila de mensagens mortas, mas não há fila: a mensagem simplesmente some, com um aviso no log. Ver §15.
  • O mascaramento acontece na gravação, não na leitura. maskSensitiveData roda antes do INSERT e é recursivo em objetos e listas. O valor sensível nunca chega ao banco, o que é o comportamento certo — e significa que a lista de campos protegidos vale a partir do momento em que foi escrita, sem efeito retroativo.
  • ipAddress e userAgent existem na tabela e nunca são preenchidos por este caminho. CreateAuditLogInput aceita os dois, e o consumidor não os fornece porque o evento não os carrega. As colunas ficam nulas. Ver §15.

Ciclo de vida da mensagem dentro do consumidor

stateDiagram-v2
  [*] --> Publicada: XADD por um building block
  Publicada --> Entregue: XREADGROUP pelo grupo audit-trail-consumers
  Entregue --> Gravada: INSERT em audit_logs
  Gravada --> Confirmada: XACK
  Confirmada --> [*]
  Entregue --> Descartada: sem metadata.organizationId — XACK sem gravar
  Entregue --> Pendente: falha na gravação, sem XACK
  Pendente --> Entregue: ociosa há mais de 30.000 ms — XCLAIM
  Pendente --> Descartada: 4ª entrega que falha (qualquer causa) — cópia em audit-trail:dead-letter, depois XACK
  Entregue --> Descartada: organização que não é UUID — cópia nas mortas (INVALID_ORGANIZATION_ID), XACK
  Descartada --> [*]

Atenção. O estado Descartada não deixa linha na trilha e não gera métrica dedicada. No caso das três entregas, a mensagem fica em audit-trail:dead-letter e o log registra, em error, event NOT written to the trail.

Monolito vs. standalone

As rotas de leitura funcionam nos dois modos. O consumidor não: ele só é iniciado pelo main.ts de standalone, e ainda assim apenas se AUDIT_CONSUMER_ENABLED for verdadeiro. Em monolito, a trilha não é populada de forma alguma. Essa é a diferença de comportamento mais relevante entre os modos em todo o catálogo, e ela não é óbvia olhando as rotas.


08

Conceitos e modelo de dados

Glossário

TermoSignifica
Evento de domínioMensagem publicada por um building block quando algo acontece: type, payload e metadata. Trafega no fluxo Redis iam-events.
Tipo de evento (eventType)O nome completo, em três partes: customers.person.created. A primeira parte é o building block, a segunda o recurso, a terceira a ação.
Ação (action)Enumeração derivada do último segmento do tipo. É o que você filtra.
Tipo de autor (actorType)user quando a metadata traz userId; api_client quando há organização e não há usuário; system no restante; customer quando o publicador declara — o cliente final do cliente (quem assinou, quem fez a prova de vida, quem aceitou a proposta). Valor fora dos quatro é ignorado, nunca gravado.
Autor (actorId)O identificador do usuário. Quando o autor é api_client, recebe o identificador da organização — o mesmo valor que o IAM usa como client_id.
Tipo de recurso (resourceType)Normalizado a partir do prefixo do evento: customers.person vira person. Prefixo desconhecido cai no primeiro segmento do tipo.
changesJSONB com before e after. Em criação, só after. Em exclusão, só before.
RetençãoDias que a trilha da organização é preservada. De 1 a 3.650. Padrão 365 quando nunca configurada.
Expurgo (cleanup)Remoção física das linhas mais antigas que a retenção. Não é exclusão lógica: o DELETE é definitivo.
Grupo de consumidoraudit-trail-consumers. Mantém a posição de leitura no fluxo Redis e permite reprocessar mensagem não confirmada.
Sequência (sequence)Número por organização, de 1 em diante, sem buraco. Atribuído dentro da transação de inserção. Linha anterior ao encadeamento tem sequence nulo — é "pré-corrente".
Elo (prevHash) e hash (hash)hash = SHA-256 hex do JSON canônico (chaves ordenadas, sem espaço) dos campos persistidos, incluindo sequence, prevHash e createdAt em ISO-8601. A primeira linha aponta para 64 zeros.
Cabeça da correnteUma linha por organização em audit_chain_heads com a última sequência e o último hash. É ela que é travada na escrita e é ela que denuncia a remoção das ÚLTIMAS linhas.
Poda (prunedThrough*)Até onde o expurgo apagou. A primeira linha sobrevivente é conferida contra esse hash — é o que distingue poda programada de remoção. Quem lê a trilha por fachada recebe esse número junto com a linha, para distinguir "nunca houve linha" de "a linha pode ter sido podada".
Tipo pinadoTipo de evento cuja última linha por recurso o expurgo nunca apaga (utils/pinned-events.ts). Existe porque há decisão de outro bloco que depende da linha existir — hoje a política de autorização do BaaS.
ÂncoraCabeça da corrente assinada em Ed25519 com a chave da organização, gravada e publicada como evento para o cliente guardar.
Pré-corrente (preChain)Quantidade de linhas anteriores ao encadeamento no intervalo verificado. Não são reescritas e não têm o que verificar.

Modelo de dados

Schema audit no PostgreSQL. 5 modelos.

Modelo PrismaTabelaPropósitoCampos-chave
AuditLogaudit.audit_logsUma linha por evento registradoorganizationId, eventType, action, actorId, actorType, resourceType, resourceId, changes (JSONB), ipAddress, userAgent, metadata (JSONB), createdAt, sequence (único por organização), prevHash, hash
OrganizationAuditConfigaudit.organization_audit_configsRetenção da organizaçãoorganizationId (único), retentionDays (padrão 365)
AuditChainHeadaudit.audit_chain_headsCabeça da corrente, travada na escritaorganizationId (chave), sequence, hash, prunedThroughSequence, prunedThroughHash
AuditAnchoraudit.audit_anchorsCarimbo assinado da cabeçaorganizationId + sequence (único), hash, keyId, signature, createdAt
AuditSigningKeyaudit.audit_signing_keysChave Ed25519 da organizaçãokeyId (único), publicKeyPem, privateKeyCipher (cifrada), retiredAt
erDiagram
  ORGANIZATION ||--o{ AUDIT_LOG : "registra"
  ORGANIZATION ||--o| ORGANIZATION_AUDIT_CONFIG : "configura"

  AUDIT_LOG {
    uuid id PK
    uuid organization_id FK
    string event_type "customers.person.created"
    string action "CREATE, UPDATE, DELETE, ..."
    uuid actor_id "nulo quando actorType e system"
    string actor_type "user, system, api_client"
    string resource_type "person, product, user, ..."
    uuid resource_id
    jsonb changes "before e after"
    bigint sequence "1, 2, 3... por organizacao; nulo em linha pre-corrente"
    string prev_hash "hash da linha anterior; 64 zeros na primeira"
    string hash "sha256 do JSON canonico dos campos persistidos"
    string ip_address "preenchido pela rota /events; nulo quando o publicador nao tinha requisicao"
    string user_agent "idem ip_address"
    jsonb metadata
    timestamp created_at
  }

  ORGANIZATION_AUDIT_CONFIG {
    uuid id PK
    uuid organization_id UK
    int retention_days "padrao 365, de 1 a 3650"
    timestamp created_at
    timestamp updated_at
  }

Índices de audit_logs: (organizationId, createdAt), (organizationId, resourceType, resourceId), (organizationId, actorId), eventType e o único (organizationId, sequence). Os três primeiros são compostos com a organização à frente — é o que sustenta o desempenho da consulta filtrada por tenant.

Observe o que não existe na tabela: updatedAt e deletedAt. AuditLog é criado e nunca atualizado pela aplicação — e agora, além disso, é encadeado: qualquer UPDATE ou DELETE feito por fora é denunciado pelo GET /verify. As implicações e os limites do que isso prova estão na §14.

Enumerações

EnumValoresObservação
AuditActionCREATE · UPDATE · DELETE · LOGIN · LOGOUT · ACCESS_DENIED · TOKEN_ISSUED · TOKEN_FAILED · RATE_LIMITED · EXPORT · ACCESSOs cinco relacionados a segurança não ocorrem hoje — ver §15
ActorTypeuser · system · api_client · customercustomer é o cliente final do cliente; só entra quando o publicador o declara em metadata.actorType. Grafia desconhecida é recusada na escrita

Como um evento vira uma linha da trilha

O ponto de partida é a mensagem publicada por um building block, com três campos:

json
{
  "type": "customers.person.updated",
  "payload": { "personId": "...", "changes": { "name": "..." } },
  "metadata": { "organizationId": "...", "userId": "...", "timestamp": "...", "traceId": "..." }
}
{
  "type": "customers.person.updated",
  "payload": { "personId": "...", "changes": { "name": "..." } },
  "metadata": { "organizationId": "...", "userId": "...", "timestamp": "...", "traceId": "..." }
}

A partir dela, o consumidor decide se grava e o que grava:

flowchart TD
  EV["Evento publicado por um building block<br/>type · payload · metadata"] --> D{"metadata.organizationId presente?"}
  D -->|"não"| X["confirma e DESCARTA<br/>nada é gravado"]
  D -->|"sim"| M["último segmento updated → UPDATE<br/>prefixo customers.person → person<br/>metadata.userId presente → user<br/>resourceId ← primeiro campo achado entre<br/>id, userId, personId, organizationId, productId, ..."]
  M --> R["maskSensitiveData em changes e metadata<br/>campo sensível vira [REDACTED]"]
  R --> I["INSERT em audit.audit_logs"]

Atenção ao resourceId. Por padrão ele é o primeiro campo encontrado na carga, na ordem id, userId, personId, organizationId, productId, fileId, projectId, decisionId, versionId, tagId, riskBandId, pricingRuleId. Uma carga que traga organizationId antes do identificador do recurso próprio grava a organização como recurso — foi exatamente o que aconteceu com baas.* e biometrics.* até 22/09/2026. Para esses tipos existe agora uma lista própria de campos (accountId, transactionId, pixKeyId, sessionId, templateId; desde o BB-5 também baas.authorization.* — accountId, deviceId, mandateId — porque o BaaS lê baas_authorization_policy/accountId de volta), e campo ausente é melhor que campo errado: sem um deles, resourceId fica nulo em vez de apontar para a organização. Ao publicar evento novo, coloque o identificador do recurso em id ou no campo nominal dele. Se o recurso não tem UUID (um host, por exemplo), declare a lista do tipo vazia e deixe o identificador no payload: ele vai inteiro para o metadata. Um id de outra forma que chegue à coluna não derruba mais a gravação — vira metadata._auditResourceRef.

Ciclo de vida de uma linha da trilha

stateDiagram-v2
  [*] --> Gravada: evento consumido
  Gravada --> Ancorada: o trabalho de âncora assina a cabeça e publica audit.anchor.created
  Ancorada --> Expurgada: POST /cleanup com AUDIT_CONFIG_MANAGE remove createdAt anterior a hoje menos retentionDays
  Gravada --> Expurgada: idem, quando nenhuma âncora a cobriu ainda
  Expurgada --> [*]

  note right of Gravada
    createdAt fixo. Não há UPDATE.
    Não há exclusão lógica.
    Nenhuma rota altera uma linha existente.
  end note

  note right of Expurgada
    DELETE FÍSICO de um PREFIXO contíguo.
    A cabeça registra até onde podou,
    então o /verify segue válido.
    A linha deixa de existir aqui —
    a âncora que o cliente guardou
    continua provando que ela existiu.
  end note

09

Referência da API

Prefixo: /audit-trail. Em monolito, a base é http://localhost:3000. Em staging, https://audit-trail.bb.stg.catalisa.app.

Todas as 10 rotas exigem authMiddleware (Bearer JWT do IAM), requirePermission(...) e o middleware local requireOrganization, que devolve 403 quando o token não carrega organizationId.

flowchart LR
  RQ["Requisição"] --> A["authMiddleware<br/>Bearer JWT do IAM, HS256 verificado localmente"]
  A -->|"401 sem token válido"| E1["Erro"]
  A --> P["requirePermission<br/>AUDIT_LOGS_READ, AUDIT_CONFIG_MANAGE ou AUDIT_EVENTS_WRITE"]
  P -->|"403 sem a permissão"| E2["Erro"]
  P --> O["requireOrganization<br/>local ao router"]
  O -->|"403 sem organizationId no token"| E3["Erro"]
  O --> H["Handler · Service · PostgreSQL"]

Consulta da trilha — /audit-trail/api/v1/logs

MétodoRotaDescriçãoPermissão
GET/audit-trail/api/v1/logsLista a trilha da organização, paginada e filtrávelAUDIT_LOGS_READ
GET/audit-trail/api/v1/logs/resource/:type/:idLinha do tempo completa de um recursoAUDIT_LOGS_READ

Cada linha devolvida traz também sequence, prevHash e hash — nulos nas linhas anteriores ao encadeamento. Para conferir a corrente sem exportar nada, use GET /verify.

Ingestão — /audit-trail/api/v1/events

MétodoRotaDescriçãoPermissão
POST/audit-trail/api/v1/eventsRecebe um evento de domínio, ou até 100 em events[], de um produtor fora deste código (o painel, um sistema parceiro) e publica no fluxo iam-events — não grava linha. 202 com {accepted, messageIds}AUDIT_EVENTS_WRITE

Corpo JSON:API: { "data": { "type": "audit-events", "attributes": { "type": "credit.operation.created", "payload": {…}, "metadata": { "timestamp"?, "correlationId"?, "userId"?, "actorType"?, "ipAddress"?, "userAgent"? } } } } ou attributes.events[] com a mesma forma. O actorType aceita user, system, api_client e customer — outro valor devolve 400. ipAddress e userAgent ausentes são carimbados da requisição: o primeiro salto do x-forwarded-for (o resto da lista é a nossa própria borda) e o user-agent. Quem sabe quem é o cliente final manda os dele, e o carimbo não sobrescreve. O type tem que ser bloco.recurso.acao (três segmentos ou mais, minúsculas) — senão 400 com o índice do evento. A organização vem do token, nunca do corpo: metadata.organizationId enviado é ignorado. Sem userId, entra o sub de quem chamou. A linha aparece quando o consumidor processar o fluxo (segundos); a resposta é 202, não 201.

O prefixo _audit é reservado. As chaves do payload vão para o metadata da linha, e toda chave que comece por _audit é descartada antes de a linha ser montada — sem erro: o 202 não muda. Essas chaves são da trilha (_auditResourceRef, _auditActorRef, _auditSourceStream, _auditSourceId) e ela as lê de volta, então nenhum produtor, interno ou externo, as escreve. Se o seu evento tem um campo com esse prefixo, renomeie.

Integridade — /audit-trail/api/v1/verify, /anchors, /keys, /export

MétodoRotaDescriçãoPermissão
GET/audit-trail/api/v1/verify?from=&to=Recalcula a corrente da organização e devolve {valid, checked, firstBrokenSequence, reason, head, preChain, anchorsChecked, prunedThroughSequence, prunedThroughHash, anchorsCoveringPruned, unchainedAfterChainStart, pendingAfterHead, range}AUDIT_LOGS_READ
GET/audit-trail/api/v1/anchorsLista as âncoras assinadas, da mais recente para a mais antiga, paginadaAUDIT_LOGS_READ
GET/audit-trail/api/v1/keysChaves de assinatura da organização — só a metade públicaAUDIT_LOGS_READ
GET/audit-trail/api/v1/export?from=&to=&format=ndjsonTransmite a trilha encadeada em NDJSON, com a âncora que a cobre na última linhaAUDIT_LOGS_READ

from e to aceitam uma sequência (inteiro) ou um instante ISO-8601; o instante é resolvido para sequência antes de qualquer verificação, porque quem ordena a corrente é a sequência. Omitir os dois verifica (ou exporta) tudo — e é o que se pede ao auditor, porque só o intervalo aberto até o fim enxerga a remoção das últimas linhas.

Motivos possíveis em reason, quando valid é false:

reasonO que aconteceu
hash_mismatchAlgum campo persistido da linha mudou — o hash recalculado não bate com o gravado
prev_hash_mismatchA linha não aponta para o hash da anterior (típico de quem edita uma linha e recalcula só o hash dela)
missing_rowA sequência pula: uma linha do meio foi apagada
missing_tailA cabeça da corrente aponta além da última linha existente: as últimas foram apagadas
unchained_rowLinha com sequência e sem hash — gravação parcial ou UPDATE que zerou a coluna
head_mismatchA cabeça não bate com a última linha verificada
head_behind_rowsA cabeça ficou atrás das linhas conferidas. Pela rota isto não acontece (a varredura para na cabeça do snapshot e declara o resto em pendingAfterHead); ver o verificador offline, que roda o mesmo algoritmo sobre o NDJSON exportado
anchor_ahead_of_headExiste âncora assinada para uma sequência que a cabeça — ou as linhas — não alcança mais. É o único motivo que pega a fraude completa: apagar as últimas linhas e reescrever a cabeça deixa o banco coerente consigo mesmo, mas não com o carimbo que já saiu assinado
unchained_row_after_chain_startLinha sem sequência criada depois de a corrente começar nesta organização: inserção por fora, disfarçada de pré-corrente. Vem com firstBrokenSequence: null e a contagem em unchainedAfterChainStart
anchor_mismatchA âncora assinada daquela sequência tem outro hash — a corrente foi reescrita DEPOIS de o cliente receber o carimbo
anchor_signature_invalidA assinatura da âncora não confere com a chave pública da organização

A cabeça é lida antes das linhas, e checked nunca a ultrapassa. A trilha continua sendo escrita enquanto a varredura corre: as linhas que chegarem depois da cabeça deste snapshot não entram em checked — elas saem em pendingAfterHead (contado até um lote de 500). Não é defeito, é trabalho para a próxima chamada; chamar /verify de novo as confere. Até 23/09/2026 elas eram conferidas assim mesmo e a resposta saía checked: 7, head.sequence: 6, valid: true — um valid que afirmava mais do que tinha sido comparado.

prunedThroughSequence e prunedThroughHash dizem até onde o expurgo podou — sempre, mesmo quando valid é true. Sem isso, uma trilha válida e uma trilha válida com metade dos eventos removidos teriam a mesma cara. anchorsCoveringPruned conta as âncoras cujas linhas já foram podadas: elas não têm o que conferir, e é a brecha descrita na §15.

preChain conta as linhas anteriores ao encadeamento (22/09/2026). Elas ficam como estão: reescrever o passado para ele parecer íntegro seria produzir uma prova falsa. Uma trilha com preChain > 0 e valid: true quer dizer "daqui para a frente eu provo; para trás, não".

format só aceita ndjson — CSV perderia o aninhamento que o hash cobre e, portanto, não seria verificável. Resposta em application/x-ndjson, uma linha por evento com {type:'audit-event', record, hash} e, no fim, {type:'audit-anchor', anchor, publicKeyPem, unanchoredTail, signedMessage}. O algoritmo de verificação offline está na §11.

Configuração — /audit-trail/api/v1/config

MétodoRotaDescriçãoPermissão
GET/audit-trail/api/v1/configRetenção vigente da organizaçãoAUDIT_LOGS_READ
PUT/audit-trail/api/v1/config/retentionDefine a retenção, de 1 a 3.650 diasAUDIT_CONFIG_MANAGE

Expurgo — /audit-trail/api/v1/cleanup

MétodoRotaDescriçãoPermissão
POST/audit-trail/api/v1/cleanupRemove fisicamente as linhas fora do prazo de retençãoAUDIT_CONFIG_MANAGE

Saúde do serviço

MétodoRotaDescrição
GET/audit-trail/healthStatus estático do serviço. Pública, não contabilizada nas 10 rotas

Atenção. A sonda não consulta o banco e não reporta o estado do consumidor de eventos. Ela responde ok com o Postgres fora do ar e com o consumidor desligado. Não use /health para concluir que a trilha está sendo gravada.

Não existe rota que grave linha diretamente, e isso é proposital: a única forma de entrar na trilha é um evento de domínio no fluxo — os blocos publicam direto, produtores externos passam por POST /events, que publica por eles com a organização do token. Também não existe GET /logs/:id — o campo links.self de cada linha aponta para /audit-trail/api/v1/logs/{id}, que não é uma rota implementada. Ver §15.


GET /audit-trail/api/v1/logs

Parâmetros de consulta

ParâmetroTipoPadrãoDescrição
page[number]inteiro1Página, mínimo 1
page[size]inteiro20Itens por página, máximo 100
filter[actorId]UUID—Quem executou. UUID inválido devolve 400
filter[resourceType]texto—Igualdade exata: person, product, user, ...
filter[resourceId]UUID—O recurso específico. Precisa ser UUID
filter[action]enum—Um valor de AuditAction. Valor fora do enum devolve 400
filter[eventType]texto—Igualdade exata do tipo completo, por exemplo products.product.updated
filter[dateFrom]data-hora ISO—Início do período, inclusivo
filter[dateTo]data-hora ISO—Fim do período, inclusivo

Ordenação fixa: createdAt decrescente. Filtros combinam com E lógico.

Resposta 200

json
{
  "data": [
    {
      "type": "audit-logs",
      "id": "d41f9b2c-6f0e-4a55-9f1a-3b7c2e8d5a10",
      "links": { "self": "/audit-trail/api/v1/logs/d41f9b2c-6f0e-4a55-9f1a-3b7c2e8d5a10" },
      "attributes": {
        "eventType": "products.product.updated",
        "action": "UPDATE",
        "actorId": "b1000000-0000-0000-0000-000000000001",
        "actorType": "user",
        "resourceType": "product",
        "resourceId": "8d2b1f47-3c5a-4e19-b0d6-7a1e9c4f2b88",
        "changes": {
          "before": null,
          "after": { "active": false }
        },
        "ipAddress": null,
        "userAgent": null,
        "metadata": {
          "correlationId": null,
          "timestamp": "2026-08-16T13:52:07.220Z",
          "traceId": "4b1e...",
          "productId": "8d2b1f47-3c5a-4e19-b0d6-7a1e9c4f2b88"
        },
        "createdAt": "2026-08-16T13:52:07.318Z"
      }
    }
  ],
  "meta": {
    "totalItems": 482, "totalPages": 25, "currentPage": 1,
    "itemsPerPage": 20, "hasNextPage": true, "hasPreviousPage": false
  },
  "links": {
    "self":  "/audit-trail/api/v1/logs?page[number]=1&page[size]=20",
    "first": "/audit-trail/api/v1/logs?page[number]=1&page[size]=20",
    "next":  "/audit-trail/api/v1/logs?page[number]=2&page[size]=20",
    "last":  "/audit-trail/api/v1/logs?page[number]=25&page[size]=20"
  }
}
{
  "data": [
    {
      "type": "audit-logs",
      "id": "d41f9b2c-6f0e-4a55-9f1a-3b7c2e8d5a10",
      "links": { "self": "/audit-trail/api/v1/logs/d41f9b2c-6f0e-4a55-9f1a-3b7c2e8d5a10" },
      "attributes": {
        "eventType": "products.product.updated",
        "action": "UPDATE",
        "actorId": "b1000000-0000-0000-0000-000000000001",
        "actorType": "user",
        "resourceType": "product",
        "resourceId": "8d2b1f47-3c5a-4e19-b0d6-7a1e9c4f2b88",
        "changes": {
          "before": null,
          "after": { "active": false }
        },
        "ipAddress": null,
        "userAgent": null,
        "metadata": {
          "correlationId": null,
          "timestamp": "2026-08-16T13:52:07.220Z",
          "traceId": "4b1e...",
          "productId": "8d2b1f47-3c5a-4e19-b0d6-7a1e9c4f2b88"
        },
        "createdAt": "2026-08-16T13:52:07.318Z"
      }
    }
  ],
  "meta": {
    "totalItems": 482, "totalPages": 25, "currentPage": 1,
    "itemsPerPage": 20, "hasNextPage": true, "hasPreviousPage": false
  },
  "links": {
    "self":  "/audit-trail/api/v1/logs?page[number]=1&page[size]=20",
    "first": "/audit-trail/api/v1/logs?page[number]=1&page[size]=20",
    "next":  "/audit-trail/api/v1/logs?page[number]=2&page[size]=20",
    "last":  "/audit-trail/api/v1/logs?page[number]=25&page[size]=20"
  }
}

ipAddress e userAgent vêm nulos: as colunas existem, e o caminho de consumo de evento não as preenche (§15).

Erros

StatusQuando
400Filtro reprovado no Zod — UUID malformado, ação fora do enum, data fora do formato ISO
401Token ausente, inválido ou expirado
403Falta AUDIT_LOGS_READ, ou o token não carrega organizationId

Lista vazia com 200 é resposta válida. Se ela vier vazia sempre, o suspeito número um é o consumidor desligado — ver §13.


GET /audit-trail/api/v1/logs/resource/:type/:id

A linha do tempo de um recurso: tudo que aconteceu com ele, do mais recente ao mais antigo.

ParâmetroDescrição
:typeO resourceType normalizado: person, product, user, organization, file, ... Não é o nome da tabela nem o prefixo do evento
:idO resourceId. Precisa ser UUID válido, senão 400

Resposta 200

json
{
  "data": [
    { "type": "audit-logs", "id": "...", "attributes": { "action": "UPDATE", "createdAt": "2026-08-16T13:52:07.318Z", "...": "..." } },
    { "type": "audit-logs", "id": "...", "attributes": { "action": "CREATE", "createdAt": "2026-07-02T09:14:55.001Z", "...": "..." } }
  ]
}
{
  "data": [
    { "type": "audit-logs", "id": "...", "attributes": { "action": "UPDATE", "createdAt": "2026-08-16T13:52:07.318Z", "...": "..." } },
    { "type": "audit-logs", "id": "...", "attributes": { "action": "CREATE", "createdAt": "2026-07-02T09:14:55.001Z", "...": "..." } }
  ]
}

Atenção — sem paginação e sem limite. Esta rota devolve todas as linhas do recurso, em um único documento. Para um recurso com histórico longo, a resposta cresce sem teto. Use GET /logs com filter[resourceId] quando precisar de página. Ver §15.


GET /audit-trail/api/v1/config

Retenção vigente. Quando a organização nunca configurou, devolve o padrão sem id e sem carimbos de tempo — a forma da resposta muda:

json
{ "data": { "type": "audit-config", "attributes": { "retentionDays": 365 } } }
{ "data": { "type": "audit-config", "attributes": { "retentionDays": 365 } } }

Depois de configurada:

json
{
  "data": {
    "type": "audit-config",
    "id": "1c9e4b77-a0d2-4f31-8e55-b2c0d9f1a3e6",
    "attributes": {
      "retentionDays": 1825,
      "createdAt": "2026-08-16T14:02:11.000Z",
      "updatedAt": "2026-08-16T14:02:11.000Z"
    }
  }
}
{
  "data": {
    "type": "audit-config",
    "id": "1c9e4b77-a0d2-4f31-8e55-b2c0d9f1a3e6",
    "attributes": {
      "retentionDays": 1825,
      "createdAt": "2026-08-16T14:02:11.000Z",
      "updatedAt": "2026-08-16T14:02:11.000Z"
    }
  }
}

Trate data.id como opcional no seu cliente.


PUT /audit-trail/api/v1/config/retention

Request — as duas formas funcionam:

json
{ "data": { "attributes": { "retentionDays": 1825 } } }
{ "data": { "attributes": { "retentionDays": 1825 } } }
json
{ "retentionDays": 1825 }
{ "retentionDays": 1825 }
CampoTipoRegra
retentionDaysinteiroDe 1 a 3650 (1 dia a 10 anos)

Responde 200 com a configuração gravada. É um upsert: cria se não existir, sobrescreve se existir.

Atenção. Reduzir a retenção não apaga nada sozinho. O expurgo só acontece quando alguém chama POST /cleanup. Isso é importante nos dois sentidos: você não perde trilha por engano ao ajustar o número, e você também não cumpre a retenção só por declará-la.


POST /audit-trail/api/v1/cleanup

Executa o expurgo da sua organização, usando a retenção vigente. Sem corpo.

Resposta 200

json
{
  "data": {
    "type": "cleanup-result",
    "attributes": {
      "organizationId": "b0000000-0000-0000-0000-000000000001",
      "deletedCount": 12480,
      "retentionDays": 365
    }
  }
}
{
  "data": {
    "type": "cleanup-result",
    "attributes": {
      "organizationId": "b0000000-0000-0000-0000-000000000001",
      "deletedCount": 12480,
      "retentionDays": 365
    }
  }
}

Atenção — a remoção é física e definitiva. Não há exclusão lógica, não há cópia, não há arquivamento e o expurgo não deixa registro de si mesmo na trilha. Leia a §14 antes de conceder AUDIT_CONFIG_MANAGE.

Uma exceção, e só uma: os tipos pinados (BB-5). O expurgo preserva, para cada (resourceType, resourceId), a linha mais nova dos tipos listados em src/audit-trail/utils/pinned-events.ts — hoje só baas.authorization.policy.changed. Sem isso uma conta parada por mais tempo que a retenção perdia a sua única linha de política, o BaaS passava a ler unanchored e o operador, ao rodar a ancoragem inicial, abençoava a linha do banco como ela estivesse — quem edita a política e espera o expurgo ganhava o carimbo. A lista é fechada e mora no código: configurável deixaria quem configura despinar exatamente a linha que protege. A marca da poda continua andando até o corte, então as sobreviventes ficam fora da faixa verificável de propósito e o GET /verify não as relê.


10

Início rápido

Do zero à primeira consulta da trilha. Credenciais em AMBIENTES.md.

Os comandos abaixo não foram executados na redação deste documento. As respostas são as previstas pelo código.

flowchart LR
  P1["1 · Autenticar no IAM"] --> P2["2 · Ver a retenção vigente"]
  P2 --> P3["3 · Consultar a trilha"]
  P3 --> P4["4 · Se vier vazia, confirmar o consumidor"]
  P4 --> P5["5 · Provocar um evento"]
  P5 --> P6["6 · Achar a linha do evento"]

1. Autenticar no IAM

bash
TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)
TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

A variável TOKEN fica com o JWT. Ele carrega o organizationId — sem esse claim, todas as seis rotas devolvem 403.

Se você criou o usuário pela API para esta prova, ele não loga ainda. POST /iam/api/v1/users devolve status: "pendente", e o login responde 401 Invalid credentials — a mesma mensagem de senha errada, então a resposta não distingue os dois casos. Ative antes: PATCH /iam/api/v1/users/:id com {"status":"ativo"}.

2. Ver a retenção vigente

bash
API=https://audit-trail.bb.stg.catalisa.app/audit-trail/api/v1

curl -s "$API/config" -H "Authorization: Bearer $TOKEN" | jq
API=https://audit-trail.bb.stg.catalisa.app/audit-trail/api/v1

curl -s "$API/config" -H "Authorization: Bearer $TOKEN" | jq
json
{ "data": { "type": "audit-config", "attributes": { "retentionDays": 365 } } }
{ "data": { "type": "audit-config", "attributes": { "retentionDays": 365 } } }

Sem id e sem carimbos: a organização ainda não configurou nada e está no padrão.

3. Consultar a trilha

bash
curl -s "$API/logs?page%5Bsize%5D=5" -H "Authorization: Bearer $TOKEN" \
  | jq '.meta.totalItems, [.data[].attributes.eventType]'
curl -s "$API/logs?page%5Bsize%5D=5" -H "Authorization: Bearer $TOKEN" \
  | jq '.meta.totalItems, [.data[].attributes.eventType]'
text
0
[]
0
[]

Com o consumidor desligado — que é o estado dos ambientes publicados hoje — a resposta é exatamente esta: 200 com lista vazia.

4. Se totalItems for 0, confirme o consumidor

Trilha vazia quase sempre significa que o consumidor de eventos não está ligado. Ele é desligado por padrão e não está habilitado nos stacks publicados.

bash
# No host do serviço audit-trail
docker service inspect <stack>_audit-trail \
  --format '{{range .Spec.TaskTemplate.ContainerSpec.Env}}{{println .}}{{end}}' \
  | grep AUDIT_CONSUMER_ENABLED
# No host do serviço audit-trail
docker service inspect <stack>_audit-trail \
  --format '{{range .Spec.TaskTemplate.ContainerSpec.Env}}{{println .}}{{end}}' \
  | grep AUDIT_CONSUMER_ENABLED

Sem retorno, a variável não está definida e o consumidor está desligado. Ver §13.

5. Provocar um evento

Com o consumidor ligado, crie um produto:

bash
PRODUCT_ID=$(curl -s -X POST https://products.bb.stg.catalisa.app/products/api/v1/products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"data":{"type":"products","attributes":{
        "name":"Teste de Auditoria","productType":"PERSONAL_LOAN",
        "description":"Produto criado para validar a trilha.",
        "minAmount":{"amount":1000,"currency":"BRL"},
        "maxAmount":{"amount":5000,"currency":"BRL"},
        "minInterestRate":0.01,"maxInterestRate":0.02,
        "minInstallments":3,"maxInstallments":12}}}' | jq -r '.data.id')
PRODUCT_ID=$(curl -s -X POST https://products.bb.stg.catalisa.app/products/api/v1/products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"data":{"type":"products","attributes":{
        "name":"Teste de Auditoria","productType":"PERSONAL_LOAN",
        "description":"Produto criado para validar a trilha.",
        "minAmount":{"amount":1000,"currency":"BRL"},
        "maxAmount":{"amount":5000,"currency":"BRL"},
        "minInterestRate":0.01,"maxInterestRate":0.02,
        "minInstallments":3,"maxInstallments":12}}}' | jq -r '.data.id')

A criação responde na hora. A publicação do evento products.product.created acontece no mesmo fluxo, e o consumo vem depois — por isso o passo seguinte espera alguns segundos.

6. Achar a linha correspondente

bash
sleep 3   # o consumo é assíncrono

curl -s "$API/logs/resource/product/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[].attributes.action'
sleep 3   # o consumo é assíncrono

curl -s "$API/logs/resource/product/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[].attributes.action'
texto
"CREATE"
"CREATE"

Se o produto foi criado e a linha não apareceu, cheque nesta ordem: o consumidor está ligado? O evento traz organizationId na metadata? O Redis está acessível pelos dois serviços?


11

Receitas

Investigar "quem alterou este registro"

Objetivo. Reconstruir a linha do tempo de um recurso específico.

bash
curl -s "$API/logs/resource/product/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {quando: .attributes.createdAt,
                   quem:   .attributes.actorId,
                   tipo:   .attributes.actorType,
                   acao:   .attributes.action,
                   mudou:  .attributes.changes}'
curl -s "$API/logs/resource/product/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {quando: .attributes.createdAt,
                   quem:   .attributes.actorId,
                   tipo:   .attributes.actorType,
                   acao:   .attributes.action,
                   mudou:  .attributes.changes}'

Armadilhas.

  • O :type é o resourceType normalizado — product, não products nem products.product. Consulte a listagem geral primeiro para descobrir os valores em uso: jq '[.data[].attributes.resourceType] | unique'.
  • Sem paginação: recurso com histórico longo devolve tudo de uma vez.
  • actorId é o identificador do usuário no IAM. Para saber o nome, consulte GET /iam/api/v1/users/:userId — o Audit Trail não resolve o nome.
  • Quando actorType for api_client, o actorId é o identificador da organização, não de uma pessoa. É o comportamento esperado de token M2M.

Extrair a trilha de um período para auditoria

Objetivo. Todas as ações de um mês, paginadas, para entregar a um auditor.

Como não há rota de exportação, o caminho é percorrer as páginas até hasNextPage virar false:

flowchart LR
  S["PAGE=1"] --> G["GET /logs com filter[dateFrom], filter[dateTo]<br/>page[size]=100"]
  G --> W["Acrescenta .data ao arquivo trilha.jsonl"]
  W --> C{"meta.hasNextPage é true?"}
  C -->|"sim"| N["PAGE = PAGE + 1"]
  N --> G
  C -->|"não"| F["Fim — wc -l trilha.jsonl"]
bash
PAGE=1
: > trilha.jsonl
while : ; do
  R=$(curl -s -G "$API/logs" \
        --data-urlencode 'filter[dateFrom]=2026-07-01T00:00:00.000Z' \
        --data-urlencode 'filter[dateTo]=2026-07-31T23:59:59.999Z' \
        --data-urlencode "page[number]=$PAGE" \
        --data-urlencode 'page[size]=100' \
        -H "Authorization: Bearer $TOKEN")
  echo "$R" | jq -c '.data[]' >> trilha.jsonl
  [ "$(echo "$R" | jq -r '.meta.hasNextPage')" = "true" ] || break
  PAGE=$((PAGE+1))
done
wc -l trilha.jsonl
PAGE=1
: > trilha.jsonl
while : ; do
  R=$(curl -s -G "$API/logs" \
        --data-urlencode 'filter[dateFrom]=2026-07-01T00:00:00.000Z' \
        --data-urlencode 'filter[dateTo]=2026-07-31T23:59:59.999Z' \
        --data-urlencode "page[number]=$PAGE" \
        --data-urlencode 'page[size]=100' \
        -H "Authorization: Bearer $TOKEN")
  echo "$R" | jq -c '.data[]' >> trilha.jsonl
  [ "$(echo "$R" | jq -r '.meta.hasNextPage')" = "true" ] || break
  PAGE=$((PAGE+1))
done
wc -l trilha.jsonl

Armadilhas.

  • Esta receita é a de leitura filtrada. Para entregar a um auditor uma trilha que ele verifique sozinho, use GET /export (receita abaixo): ela transmite tudo em NDJSON com a âncora assinada, e não tem limite de 100 por página.
  • As datas precisam ser ISO 8601 completas, com hora. 2026-07-01 sozinho é reprovado com 400.
  • O token expira, por padrão, em uma hora. Extração longa precisa renovar no meio.
  • O arquivo gerado contém dado da sua organização, possivelmente pessoal. Trate-o como a base — não é porque saiu por API que deixou de ser dado sensível.

Provar ao auditor que a trilha não foi adulterada

Objetivo. Responder "como sei que essa linha não mudou depois?" sem pedir que ninguém confie em nós.

bash
# 1. a corrente inteira, do começo ao fim — só o intervalo aberto enxerga remoção das ÚLTIMAS linhas
curl -s "$API/verify" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# { "valid": true, "checked": 128394, "firstBrokenSequence": null, "reason": null,
#   "head": { "sequence": 128394, "hash": "9f2c…" }, "preChain": 4120, "anchorsChecked": 96 }
# 1. a corrente inteira, do começo ao fim — só o intervalo aberto enxerga remoção das ÚLTIMAS linhas
curl -s "$API/verify" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# { "valid": true, "checked": 128394, "firstBrokenSequence": null, "reason": null,
#   "head": { "sequence": 128394, "hash": "9f2c…" }, "preChain": 4120, "anchorsChecked": 96 }

Armadilhas.

  • preChain maior que zero é esperado em organização antiga: são as linhas anteriores a 22/09/2026, que não foram reescritas. Diga isso ao auditor antes que ele pergunte.
  • valid: false com reason: 'missing_row' não prova má-fé: prova que uma linha sumiu. Pode ser restauração de banco, pode ser expurgo feito por fora. O que o encadeamento garante é que ninguém apaga em silêncio.
  • Verificar um intervalo no meio da corrente (from=1000&to=2000) parte do hash gravado da linha 999. Serve para localizar o estrago, não para provar o conjunto — para isso, from e to vazios.

Exportar e verificar a trilha OFFLINE

Objetivo. Entregar a um terceiro um arquivo que ele verifique sozinho, com a chave pública e nada mais.

bash
curl -s "$API/export?from=2026-07-01T00:00:00.000Z&to=2026-07-31T23:59:59.999Z" \
  -H "Authorization: Bearer $TOKEN" -o trilha.ndjson
tail -1 trilha.ndjson | jq '{sequence: .anchor.sequence, unanchoredTail, publicKeyPem}'
curl -s "$API/export?from=2026-07-01T00:00:00.000Z&to=2026-07-31T23:59:59.999Z" \
  -H "Authorization: Bearer $TOKEN" -o trilha.ndjson
tail -1 trilha.ndjson | jq '{sequence: .anchor.sequence, unanchoredTail, publicKeyPem}'

O algoritmo, que é o mesmo que o GET /verify roda do nosso lado:

  1. Cada linha de evento é {"type":"audit-event","record":{…},"hash":"…"}. Recalcule sha256(canonicalJson(record)) em hexadecimal e compare com hash.
    • canonicalJson: chaves de cada objeto ordenadas por código de unidade UTF-16, sem espaço nenhum, arrays na ordem em que estão, null para ausente (é o RFC 8785 na prática — a serialização de número é a do ECMAScript).
    • record tem exatamente os campos persistidos: id, organizationId, sequence, prevHash, eventType, action, actorId, actorType, resourceType, resourceId, changes, ipAddress, userAgent, metadata, createdAt (ISO-8601 com milissegundos).
  2. O elo: record.prevHash da primeira linha é 64 zeros se sequence for 1; das demais, é o hash da linha anterior. E sequence cresce de 1 em 1 — buraco é linha apagada.
  3. A âncora, na última linha: monte a mensagem organizationId|sequence|hash|createdAt|keyId (o arquivo já a traz pronta em signedMessage) e verifique a assinatura Ed25519 em base64 com o publicKeyPem. Depois confirme que a linha de evento daquela sequence tem exatamente o anchor.hash.
  4. unanchoredTail diz quantas linhas exportadas vieram DEPOIS da âncora: elas fecham a corrente, mas ainda não têm testemunha fora da plataforma. Se isso importar, exporte de novo depois da próxima âncora.
python
# verificador mínimo, sem dependência de nada nosso
import json, hashlib
from cryptography.hazmat.primitives.serialization import load_pem_public_key

def canonical(v):
    if isinstance(v, dict):
        return "{" + ",".join(f"{json.dumps(k)}:{canonical(v[k])}" for k in sorted(v)) + "}"
    if isinstance(v, list):
        return "[" + ",".join(canonical(x) for x in v) + "]"
    return json.dumps(v, separators=(",", ":"), ensure_ascii=False)

prev, expected, hashes = None, None, {}
for line in open("trilha.ndjson"):
    obj = json.loads(line)
    if obj["type"] == "audit-event":
        r = obj["record"]
        assert hashlib.sha256(canonical(r).encode()).hexdigest() == obj["hash"], r["sequence"]
        assert prev is None or r["prevHash"] == prev, r["sequence"]
        assert expected is None or r["sequence"] == expected, expected
        prev, expected = obj["hash"], r["sequence"] + 1
        hashes[r["sequence"]] = obj["hash"]
    elif obj["type"] == "audit-anchor" and obj["anchor"]:
        a = obj["anchor"]
        load_pem_public_key(obj["publicKeyPem"].encode()).verify(
            __import__("base64").b64decode(a["signature"]), obj["signedMessage"].encode()
        )
        assert hashes[a["sequence"]] == a["hash"]
print("trilha íntegra")
# verificador mínimo, sem dependência de nada nosso
import json, hashlib
from cryptography.hazmat.primitives.serialization import load_pem_public_key

def canonical(v):
    if isinstance(v, dict):
        return "{" + ",".join(f"{json.dumps(k)}:{canonical(v[k])}" for k in sorted(v)) + "}"
    if isinstance(v, list):
        return "[" + ",".join(canonical(x) for x in v) + "]"
    return json.dumps(v, separators=(",", ":"), ensure_ascii=False)

prev, expected, hashes = None, None, {}
for line in open("trilha.ndjson"):
    obj = json.loads(line)
    if obj["type"] == "audit-event":
        r = obj["record"]
        assert hashlib.sha256(canonical(r).encode()).hexdigest() == obj["hash"], r["sequence"]
        assert prev is None or r["prevHash"] == prev, r["sequence"]
        assert expected is None or r["sequence"] == expected, expected
        prev, expected = obj["hash"], r["sequence"] + 1
        hashes[r["sequence"]] = obj["hash"]
    elif obj["type"] == "audit-anchor" and obj["anchor"]:
        a = obj["anchor"]
        load_pem_public_key(obj["publicKeyPem"].encode()).verify(
            __import__("base64").b64decode(a["signature"]), obj["signedMessage"].encode()
        )
        assert hashes[a["sequence"]] == a["hash"]
print("trilha íntegra")

Armadilhas.

  • O arquivo sai em fluxo. Se a conexão cair no meio, a última linha não será a âncora — e uma última linha {"type":"export-error"} diz que a exportação foi interrompida. Não trate arquivo truncado como trilha completa.
  • Linhas pré-corrente não saem na exportação: ela só transmite o que é verificável. Para as antigas, use GET /logs.
  • Guarde as âncoras que chegam pelo webhook audit.anchor.created. É a cópia que nos põe fora do caminho — sem ela, o arquivo só prova que a corrente é coerente consigo mesma.

Descobrir por que um evento não apareceu na trilha

Objetivo. Diagnóstico em ordem, do mais provável ao menos.

flowchart TD
  Q["Publiquei o evento e ele não apareceu na trilha"] --> C1{"AUDIT_CONSUMER_ENABLED ligado<br/>e serviço em modo standalone?"}
  C1 -->|"não"| F1["Causa nº 1 — o consumidor não sobe.<br/>Em monolito ele nunca é iniciado"]
  C1 -->|"sim"| C2{"O evento chegou ao fluxo?<br/>XLEN iam-events"}
  C2 -->|"não"| F2["O serviço de origem não publica evento para essa operação"]
  C2 -->|"sim"| C3{"O evento traz metadata.organizationId?"}
  C3 -->|"não"| F3["Descartado em silêncio — confirma e ignora"]
  C3 -->|"sim"| C4{"XPENDING acusa mensagem parada?"}
  C4 -->|"sim"| F4["Falha de gravação, ou mais de 3 entregas.<br/>Veja XLEN audit-trail:dead-letter e o log event NOT written to the trail"]
  C4 -->|"não"| F5["Verifique o Redis e a conectividade dos dois serviços"]

1. O consumidor está ligado? É a causa nº 1. AUDIT_CONSUMER_ENABLED precisa ser verdadeiro no serviço audit-trail, e o serviço precisa estar em modo standalone. Confirme no log de inicialização:

bash
docker service logs <stack>_audit-trail 2>&1 | grep -i "audit consumer"
docker service logs <stack>_audit-trail 2>&1 | grep -i "audit consumer"
text
Audit consumer started successfully
Audit consumer started successfully

Essa linha sai em nível warn justamente para aparecer no padrão de produção: com NODE_ENV=production e sem LOG_LEVEL, o nível efetivo é warn e tudo que é info some. É uma linha por processo — se ela não está lá, o consumidor não subiu.

Se em vez disso aparecer Audit consumer is disabled (AUDIT_CONSUMER_ENABLED=false), pare por aqui: nada será gravado. Essa linha é info: para vê-la (e ao resto da partida, como Audit Trail service running), suba o serviço com LOG_LEVEL=info.

2. O evento chegou ao fluxo Redis?

bash
redis-cli XLEN iam-events
redis-cli XREVRANGE iam-events + - COUNT 5
redis-cli XLEN iam-events
redis-cli XREVRANGE iam-events + - COUNT 5

Se o XLEN não cresce quando você provoca a operação, o problema é na origem: aquele serviço não publica evento para essa operação.

3. O evento traz organizationId na metadata? Sem ele, o consumidor CONFIRMA e DESCARTA — silenciosamente.

bash
redis-cli XREVRANGE iam-events + - COUNT 1 | grep -o '"organizationId":"[^"]*"'
redis-cli XREVRANGE iam-events + - COUNT 1 | grep -o '"organizationId":"[^"]*"'

Sem retorno, o evento não tem tenant e nunca virará linha.

4. Há mensagem pendente no grupo do audit-trail?

bash
redis-cli XPENDING iam-events audit-trail-consumers
redis-cli XPENDING iam-events audit-trail-consumers

Contagem de pendentes crescendo indica falha de gravação — o consumidor não confirma a mensagem e ela volta na varredura.

Ordem de suspeita.

  1. AUDIT_CONSUMER_ENABLED desligado, ou serviço rodando em modo monolito — nesse modo o consumidor nunca é iniciado.
  2. Evento sem metadata.organizationId — descartado sem erro visível.
  3. O serviço de origem não publica evento para essa operação. Nem toda operação de todo building block publica; a publicação é escrita à mão em cada serviço.
  4. Mensagem entregue mais de três vezes e descartada. Ela está em audit-trail:dead-letter (XLEN, XRANGE); no log do audit-trail, event NOT written to the trail.

Mensagens mortas — reprocessar ou descartar. O comando roda dentro do serviço audit-trail implantado (é uma entrada do build, dist/audit-trail/dead-letter.mjs; a imagem leva dist/, não src/ nem scripts/), com o DATABASE_URL/REDIS_URL do próprio serviço. Uma linha de JSON na saída:

bash
bun run dist/audit-trail/dead-letter.mjs count
bun run dist/audit-trail/dead-letter.mjs replay 100
# → {"examined":…,"written":…,"skippedAlreadyWritten":…,"stillFailing":…,"impossible":…,"inProgressElsewhere":…}
bun run dist/audit-trail/dead-letter.mjs discard 1791842652334-0                  # uma, pelo id DA MORTA
bun run dist/audit-trail/dead-letter.mjs discard --reason INVALID_ORGANIZATION_ID # todas as de um motivo
bun run dist/audit-trail/dead-letter.mjs count
bun run dist/audit-trail/dead-letter.mjs replay 100
# → {"examined":…,"written":…,"skippedAlreadyWritten":…,"stillFailing":…,"impossible":…,"inProgressElsewhere":…}
bun run dist/audit-trail/dead-letter.mjs discard 1791842652334-0                  # uma, pelo id DA MORTA
bun run dist/audit-trail/dead-letter.mjs discard --reason INVALID_ORGANIZATION_ID # todas as de um motivo

Ver quais são, sem o comando: redis-cli XRANGE audit-trail:dead-letter - + COUNT 5 (tipo, origem, entregas, reason, errorCode).

  • replay grava direto na trilha — o mesmo mapeamento e o mesmo logEvent do consumidor. written é linha nova; stillFailing continua na lista (a causa não foi consertada).
  • É idempotente. A linha reprocessada leva a origem no metadata (_auditSourceStream, _auditSourceId — o fluxo e o id da mensagem original), e antes de gravar o comando pergunta ao banco se já existe linha dessa origem — primeiro só entre as linhas criadas a partir de 10 minutos antes do deadLetteredAt da morta (uma linha reprocessada nasce depois de a mensagem morrer), o que deixa a busca no índice (organization_id, created_at); se essa busca não acha, ela é refeita sem o limite antes de gravar — a mesma origem pode reaparecer numa morta com instante posterior à linha (marca de cópia de 7 dias vencida, morta recolocada à mão, relógios divergentes), e um "não achei" limitado gravaria a segunda linha. A busca cara só roda quando o comando vai gravar: se existe, só tira a morta da lista (skippedAlreadyWritten). Rodar duas vezes, ou rodar de novo depois de um replay interrompido, não duplica linha. Duas execuções ao mesmo tempo são separadas por uma trava curta por mensagem no Redis (audit-trail:dead-letter:replaying:…, 5 min); a que encontra a trava deixa a morta para a outra (inProgressElsewhere).
  • A linha reprocessada entra na PONTA da corrente, com sequence e createdAt de agora — a corrente não aceita linha no meio. O instante original do evento segue em metadata.timestamp; para ordenar pelo que aconteceu, use ele.
  • impossible são as mortas que nenhum reprocessamento grava (reason: INVALID_ORGANIZATION_ID: não há trilha para elas). Não gastam o limite nem prendem as seguintes (a lista é percorrida por cursor), e só saem com discard.
  • discard apaga sem gravar e loga em error o que foi descartado (id, tipo, origem, motivo) — nunca o corpo.

Nunca republique uma morta no iam-events. O barramento é lido por todos os grupos (webhook-delivery-consumers, analytics, wpp…): um XADD do evento de volta entrega o webhook ao cliente pela segunda vez e faz o analytics contar de novo — a trilha era o único leitor que tinha ficado sem ele. Por isso o reprocessamento não publica nada. Republicar só é aceitável no platform-operator-events, que tem um único leitor (a trilha), e mesmo lá o caminho é o comando acima.

Mensagem descartada antes de 12/10/2026 não está nessa lista (só houve o XACK): ela continua no fluxo de origem, que não tem MAXLEN.

Passo de ambiente (uma vez por ambiente, e alerta permanente):

  1. Conferir que o usuário Redis do bb-audit-trail pode escrever as chaves novas — audit-trail:dead-letter (XADD, XRANGE, XDEL, XLEN), audit-trail:dead-letter:copied:* e audit-trail:dead-letter:replaying:* (SET, DEL): redis-cli ACL GETUSER <usuário>. Sem a permissão o serviço segue de pé e loga NOT copied a cada mensagem que desistir de gravar.
  2. Alerta em XLEN audit-trail:dead-letter > 0 (ou no log event NOT written to the trail): cada entrada é um evento que não entrou na trilha.
  3. No Postgres do ambiente, idle_in_transaction_session_timeout no usuário da aplicação (por exemplo ALTER ROLE <usuário da aplicação> SET idle_in_transaction_session_timeout = '60s'). É isto — não o limite de espera da trilha — que solta a trava de quem ficou pendurado. O limite de espera acima impede que uma trava presa pare a trilha de todos, mas não solta a trava: a organização dona dela segue sem gravar (e acumulando mortas) até a sessão que a segura acabar. Com esse parâmetro o próprio banco encerra a sessão que ficou parada dentro de uma transação. Hoje não é definido por este repositório.
  4. Falta (PR seguinte): o sinal de "fluxo parado há X". GET /audit-trail/health não diz se o consumidor está andando. Até existir, o que denuncia um fluxo parado é XPENDING <fluxo> audit-trail-consumers crescendo e a idade da pendente mais antiga.

Definir retenção diferente por cliente

Objetivo. Cinco anos para os clientes enterprise, um ano para os demais.

bash
# Cinco anos para esta organização (o token define de qual organização se trata)
curl -s -X PUT "$API/config/retention" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"retentionDays": 1825}' | jq '.data.attributes'
# Cinco anos para esta organização (o token define de qual organização se trata)
curl -s -X PUT "$API/config/retention" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"retentionDays": 1825}' | jq '.data.attributes'
json
{ "retentionDays": 1825, "createdAt": "...", "updatedAt": "..." }
{ "retentionDays": 1825, "createdAt": "...", "updatedAt": "..." }

Armadilhas.

  • A configuração é sempre da organização do token. Não há rota para configurar a retenção de outra organização — cada uma precisa de um token próprio.
  • Declarar a retenção não executa nada. Sem POST /cleanup, a trilha cresce indefinidamente.
  • Aumentar a retenção não recupera o que já foi expurgado. O DELETE é físico.

Executar o expurgo com segurança

Objetivo. Aplicar a retenção sem apagar mais do que deveria.

1. SEMPRE confira a retenção vigente antes

bash
curl -s "$API/config" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.retentionDays'
curl -s "$API/config" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.retentionDays'
text
365
365

2. Meça o que existe fora do prazo (365 dias, no exemplo)

bash
CUT=$(date -u -d '365 days ago' +%Y-%m-%dT%H:%M:%S.000Z)
curl -s -G "$API/logs" --data-urlencode "filter[dateTo]=$CUT" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'
CUT=$(date -u -d '365 days ago' +%Y-%m-%dT%H:%M:%S.000Z)
curl -s -G "$API/logs" --data-urlencode "filter[dateTo]=$CUT" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

O número que sai aqui é a ordem de grandeza do que o passo 3 vai apagar.

3. Só então execute

bash
curl -s -X POST "$API/cleanup" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
curl -s -X POST "$API/cleanup" -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
json
{ "organizationId": "b0000000-0000-0000-0000-000000000001", "deletedCount": 12480, "retentionDays": 365 }
{ "organizationId": "b0000000-0000-0000-0000-000000000001", "deletedCount": 12480, "retentionDays": 365 }

Armadilhas.

  • Não há confirmação, não há simulação e não há volta. A chamada apaga fisicamente e devolve a contagem depois do fato.
  • Quem tem AUDIT_CONFIG_MANAGE pode reduzir a retenção para 1 dia e chamar o expurgo, removendo quase toda a trilha da própria organização em duas chamadas. Isso é limitação de projeto e está na §14 e na §15 — conceda essa permissão a poucas contas e trate como privilégio elevado.
  • O expurgo não registra a si mesmo na trilha. Não há linha dizendo que ele aconteceu.

12

Integração com outros building blocks

Building blockComo se relacionaObrigatório
IAMEmite o token com organizationId e as permissões AUDIT_*. Publica iam.user.*, iam.organization.* e iam.association.*Sim
CustomersPublica customers.person.created, .updated, .deletedNão
ProductsPublica products.product.created, .updated, .deletedNão
BillingPublica eventos de plano, produto, medidor e configuraçãoNão
API KeysPublica criação, rotação, revogação e uso de chaveNão
File StoragePublica criação, envio e exclusão de arquivoNão
Feature FlagsPublica criação e alternância de flagNão
Webhooks EngineLê o mesmo fluxo Redis, em grupo de consumidor próprio. E é por ele que a âncora chega ao cliente: assine audit.anchor.created (ou audit.*) na organização para receber o carimbo assinado da cabeça da corrente — é a cópia que fica fora do nosso alcance (§14)Não, mas é o que dá valor à âncora
BaaS e BiometricsPublicam baas.* e biometrics.*. Desde 22/09/2026 classificam como baas_account, baas_pix_transfer, biometrics_session, … com o identificador do recurso — antes caíam no espaço de nomes cru com o id da organização como recurso. BB-5: baas.authorization.* classifica como baas_authorization_policy (por accountId), baas_device_key, baas_mandate e baas_authorization; e o BaaS lê a trilha de volta pela fachada IAuditTrailFacade (GET /logs filtrado por recurso e tipo) para conferir a política da conta contra a última baas.authorization.policy.changed antes de cada escrita — a trilha virou dependência de disponibilidade do BaaS (README do BaaS, §14 e §15)Sim — o BaaS, por MODULE_AUDIT_TRAIL_URL
Demais building blocks que publicamAparecem na trilha sem alteração aqui: a ação e o tipo de recurso são derivados do nome do eventoNão
flowchart TD
  IAM["IAM"] --> ST
  CUS["Customers"] --> ST
  PRO["Products"] --> ST
  BIL["Billing"] --> ST
  FST["File Storage"] --> ST
  ETC["..."] --> ST
  ST(["Redis Stream iam-events<br/>publicação EXPLÍCITA — cada serviço chama publish"])
  ST -->|"grupo audit-trail-consumers"| AT["AUDIT TRAIL<br/>audit_logs"]
  ST -->|"grupo webhook-consumers"| WE["Webhooks Engine<br/>entrega externa"]
  AT -->|"AUDIT_LOGS_READ"| CLI["A empresa cliente consulta<br/>a PRÓPRIA trilha por API"]
  AT -->|"audit.anchor.created<br/>âncora assinada da cabeça"| ST
  WE -->|"entrega a âncora"| CLI

Building blocks que publicam evento: 25 dos 32. Cobertura = o que os building blocks publicam. Nem tudo é publicado.

Este diagrama é o argumento comercial e o limite dele, na mesma imagem. O ganho é real: a trilha existe porque os blocos vizinhos já publicam, e um bloco novo entra sem trabalho de integração. O limite também é real: o que ninguém publica não aparece, e a trilha não tem como avisar que está incompleta. Diga as duas coisas na mesma frase — é o que sobrevive à auditoria técnica do comprador.


13

Configuração e operação

Variáveis de ambiente

VariávelDescriçãoObrigatóriaPadrão
AUDIT_CONSUMER_ENABLEDLiga o consumidor que popula a trilha. Sem ele verdadeiro, nada é gravadoNãofalse
AUDIT_TRAIL_SIGNING_MASTER_KEY64 hexadecimais (32 bytes). Cifra a chave privada Ed25519 de cada organização. Master key própria deste bloco — quem a tem forja a prova de integridade da trilha inteiraSó para âncora—
AUDIT_ANCHOR_ENABLEDLiga o trabalho que assina a cabeça da correnteNãotrue (inerte sem a chave acima)
AUDIT_ANCHOR_INTERVAL_MINUTESIntervalo entre passadas do trabalho de âncoraNão60
DATABASE_URLPostgreSQL. O BB usa o schema auditSim—
REDIS_URLRedis. Fluxo iam-events e limite de taxaSim—
JWT_SECRETSegredo HS256 do IAM, mínimo 44 caracteresSim—
PORTPorta em modo standaloneNão3000 (a topologia usa 3008)
DEPLOYMENT_MODEmonolith ou standalone. O consumidor só inicia em standaloneNãomonolith
RATE_LIMIT_ENABLEDLiga o limite global de taxaNãotrue no código; os stacks definem false
CORS_ORIGINSOrigens permitidas, separadas por vírgulaNãovazio

Atenção — leia esta linha antes de operar. AUDIT_CONSUMER_ENABLED tem padrão false. Desde 10/09/2026, deploy/docker-stack.staging.yml e deploy/docker-stack.prod.yml a definem como 'true' só no serviço audit-trail (dois consumidores no mesmo grupo dividiriam as mensagens sem ganho). O consumidor também só é iniciado pelo main.ts de standalone — em monolito ele nunca sobe. Num ambiente montado à mão sem a variável, as rotas de leitura respondem e a trilha está vazia.

Cuidado adicional com o valor: a variável é interpretada por coerção de booleano. AUDIT_CONSUMER_ENABLED=false como texto não desliga — a forma de manter desligado é não definir a variável. Para ligar, use true e confirme no log de inicialização a linha Audit consumer started successfully — ela sai em warn, o nível efetivo de NODE_ENV=production sem LOG_LEVEL, justamente para não depender de ninguém lembrar de baixar o nível.

Em desenvolvimento local, o orquestrador scripts/dev-standalone.ts força AUDIT_CONSUMER_ENABLED=true quando o serviço audit-trail está no conjunto selecionado — por isso a trilha é populada na sua máquina e não é nos ambientes publicados.

Sobre a chave de assinatura. Sem AUDIT_TRAIL_SIGNING_MASTER_KEY o trabalho de âncora não sobe e diz por quê no log (Audit anchor job not started: AUDIT_TRAIL_SIGNING_MASTER_KEY is not configured). O encadeamento, o GET /verify e o GET /export continuam funcionando — o que falta é a testemunha externa. A chave entra pelo SOPS (scripts/envs/secrets.*.enc.env), como as dos outros blocos, e rotacioná-la exige recifrar as chaves privadas existentes: as âncoras já assinadas continuam verificáveis pela pública, mas sem a master key antiga nenhuma âncora nova sai. Gere com openssl rand -hex 32.

Dependências de infraestrutura

DependênciaPara quêSe cair
PostgreSQLSchema audit, cinco tabelasLeitura e escrita falham com 500 INTERNAL
RedisFluxo iam-events, grupo audit-trail-consumers, trava do trabalho de âncoraA trilha para de ser gravada; as rotas de leitura e o /verify continuam funcionando. Os eventos permanecem no fluxo e são reprocessados quando o Redis voltar. Sem trava, o trabalho de âncora não roda — e a unicidade (organização, sequência) evita âncora duplicada de qualquer forma
IAMEmissão do token. A verificação é localSem token novo; tokens válidos seguem funcionando

Comportamento do trabalho de âncora

ParâmetroValorOnde
IntervaloAUDIT_ANCHOR_INTERVAL_MINUTES, padrão 60 minjobs/index.ts
Primeira passada30 s após subiridem (deploy frequente zera o setInterval)
Trava entre réplicasaudit-trail:anchor:lock no Redis, TTL 600 sjobs/anchor.job.ts
Organizações por passadaaté 500, as de cabeça mais antiga primeiroconsulta em audit-anchor.repository.ts
Quando ancorasó se a cabeça andou desde a última âncorasenão o cliente receberia um webhook por hora dizendo que nada mudou
Idempotênciaúnico (organização, sequência); a réplica perdedora não publica eventotabela audit_anchors

Comportamento do consumidor

ParâmetroValorOnde
Fluxoiam-eventsaudit-consumer.ts
Grupo de consumidoraudit-trail-consumersaudit-consumer.ts
Nome do consumidoraudit-consumer-{pid}um por processo
Mensagens por leitura10COUNT
Espera bloqueante5.000 msBLOCK
Tempo ocioso para reivindicar pendente30.000 msvarredura de pendências
Máximo de entregas3acima disso a mensagem é confirmada e descartada

Limites

LimiteValor
Itens por página na listagem100
Linha do tempo por recursosem limite e sem paginação
Retenção1 a 3.650 dias
Retenção padrão365 dias
Tamanho do corpo1 MB
Linhas por lote na verificação e na exportação500 (transmitido em fluxo; a exportação não tem teto)
Âncoras conferidas por verificação5.000

Catálogo de erros

StatusCódigoSignificaO que fazer
400—Filtro reprovado no ZodUUID malformado, ação fora do enum, data sem formato ISO completo
400—retentionDays fora de 1 a 3650Ajuste o valor
401—Token ausente, inválido ou expiradoRenove pelo refresh token do IAM
403—Falta AUDIT_LOGS_READ ou AUDIT_CONFIG_MANAGEConfira papel e permissões da organização no IAM
403—Token sem organizationIdAutentique informando a organização
429—Limite de taxa por IPRecuo exponencial; use o Retry-After
500INTERNALFalha de bancoVerifique o Postgres antes de investigar código

Note que não há 404 na trilha: consulta a recurso inexistente devolve 200 com lista vazia.

Observabilidade

  • GET /audit-trail/health reporta o processo. Não reporta banco nem estado do consumidor.
  • O consumidor loga a inicialização (Starting audit consumer, Created consumer group), cada mensagem processada em nível de depuração, e erros de gravação em nível de erro.
  • Mensagem descartada por excesso de tentativas vai para audit-trail:dead-letter e gera, em error, event NOT written to the trail — vale um alerta (XLEN audit-trail:dead-letter > 0), porque é evento que não entrou na trilha.
  • Cada mensagem é processada dentro de um span ligado ao trace da requisição original, através do traceId propagado na metadata do evento. Dá para ir da criação do produto até a linha da trilha no mesmo trace.
  • Para acompanhar acúmulo, monitore XPENDING iam-events audit-trail-consumers e o tamanho do fluxo com XLEN.

14

Segurança e compliance

Isolamento entre organizações

O organizationId é claim assinado do JWT. As dez rotas aplicam requireOrganization e passam o valor adiante (a ingestão carimba esse valor no evento e descarta qualquer organização vinda do corpo); findMany, findByResource, a poda do expurgo, a verificação, a exportação, as âncoras e as chaves incluem a organização na cláusula where — inclusive a corrente, que é uma por organização: não existe sequência global cujo formato vaze o volume de outro cliente. No caminho de escrita, o isolamento é ainda mais estrito: evento sem metadata.organizationId não é gravado, porque não haveria tenant a que atribuí-lo. Não existe rota que devolva linha de outra organização, e não existe consulta cruzada — nem para conta com isRoot.

flowchart LR
  J["JWT assinado<br/>claim organizationId"] --> RD["Leitura<br/>findMany · findByResource · deleteExpired · config"]
  RD --> WH["where organizationId = claim"]
  EVT["Evento no fluxo"] --> CK{"metadata.organizationId?"}
  CK -->|"ausente"| NO["não é gravado — sem tenant a que atribuir"]
  CK -->|"presente"| WR["INSERT com o organizationId do evento"]
  WH --> ISO["Sem consulta cruzada — nem para conta com isRoot"]
  WR --> ISO

Autenticação e permissões

Bearer JWT do IAM, HS256 verificado localmente. Duas permissões, com pesos bem diferentes:

PermissãoConcedeRisco
AUDIT_LOGS_READLer a trilha e a configuraçãoLeitura de dado potencialmente pessoal — ver abaixo
AUDIT_CONFIG_MANAGEAlterar a retenção e executar o expurgoDestruição de trilha. Trate como privilégio elevado

Dado sensível na trilha

O maskSensitiveData roda antes do INSERT, é recursivo em objetos e listas, e substitui por [REDACTED] todo campo cujo nome contenha um destes termos, sem diferenciar maiúsculas:

CategoriaTermos que disparam o mascaramento
Senhapassword, passwordHash, password_hash
Segredosecret, clientSecret, client_secret, mfaSecret, mfa_secret
Tokentoken, accessToken, access_token, refreshToken, refresh_token
Chave e cabeçalhoapiKey, api_key, authorization
flowchart LR
  IN["changes e metadata do evento"] --> MK["maskSensitiveData<br/>recursivo em objetos e listas"]
  MK -->|"nome do campo contém password, secret, token, apiKey, authorization"| RE["[REDACTED]"]
  MK -->|"CPF, nome, e-mail, telefone, endereço, renda"| TX["gravado em texto"]
  RE --> DB[("audit.audit_logs")]
  TX --> DB

A lista não inclui dado pessoal. CPF, nome, e-mail, telefone, endereço e renda passam sem mascaramento e ficam gravados em texto na coluna changes. Isso é consequência direta do desenho — a trilha precisa registrar o antes e o depois, e um "antes" mascarado não serve para auditoria. Mas tem duas implicações que precisam estar claras:

  1. Conceder AUDIT_LOGS_READ é conceder acesso a dado pessoal, mesmo para quem não tem permissão no building block de origem. Alguém sem CUSTOMERS_PEOPLE_READ pode ver o CPF de um cliente lendo a trilha. Trate a permissão com o mesmo rigor que trataria o acesso ao cadastro.
  2. A trilha herda a obrigação de proteção do dado que registra. Ela é um repositório de dado pessoal como qualquer outro, sujeita às mesmas exigências de acesso, retenção e eliminação.

Não há cifragem de campo em audit_logs. Não há mascaramento de CPF na resposta.

O log é imutável? Não — é à prova de EVIDÊNCIA, e a diferença é a que o auditor cobra

O que é garantido:

  • Não existe rota de alteração. Nenhum endpoint faz UPDATE em AuditLog, e a tabela não tem updatedAt nem deletedAt.
  • Não existe rota que grave linha. POST /events publica no fluxo com a organização do token, e o consumidor é quem grava — ninguém forja uma linha de outra organização por HTTP, e o mascaramento de campos sensíveis vale para o evento externo como para o interno.
  • Não existe exclusão de linha individual. Não há DELETE /logs/:id.
  • Toda alteração feita por fora é detectável. Desde 22/09/2026 cada linha traz sequência, hash do próprio conteúdo e hash da anterior. Editar uma linha quebra o hash dela; recalcular o hash dela quebra o elo da seguinte; apagar uma do meio abre buraco na sequência; apagar as últimas deixa a cabeça da corrente apontando para o vazio. GET /verify devolve a primeira sequência quebrada e o motivo.
  • Existe uma testemunha fora do nosso alcance. O trabalho de âncora assina a cabeça da corrente com a chave Ed25519 da organização e publica audit.anchor.created, que o webhooks-engine entrega ao endpoint do cliente. Reescrever a corrente inteira no banco — o que quem tem acesso administrativo consegue fazer — passa a ser detectável por qualquer âncora que o cliente tenha guardado: GET /verify confere cada âncora contra a linha recalculada e acusa anchor_mismatch.
  • A cabeça sozinha não é prova, e a verificação sabe disso. audit_chain_heads é tabela comum: quem apaga as últimas linhas pode reescrever a cabeça junto e deixar o banco coerente consigo mesmo. Por isso, depois de recalcular a corrente, a verificação reconcilia com as âncoras: se a maior âncora aponta para uma sequência que ninguém alcança mais, a resposta é anchor_ahead_of_head. É o carimbo assinado, e não a nossa tabela, que fecha a cauda.
  • Linha plantada sem elo é denunciada. Um INSERT direto sem sequence se disfarçaria de linha pré-corrente. A cabeça guarda chain_started_at, e qualquer linha sem sequência criada depois desse instante quebra a verificação (unchained_row_after_chain_start).
  • A extração é verificável por terceiro. GET /export entrega NDJSON com os campos exatos que entram no hash e a âncora assinada; o algoritmo está publicado na §11 e não depende de nada nosso.

O que não é garantido:

  • Não há armazenamento WORM. As linhas ficam numa tabela PostgreSQL comum. Quem tem acesso administrativo ao banco continua podendo UPDATE e DELETE — o que mudou é que isso deixa de ser silencioso. O encadeamento não impede: denuncia.
  • A âncora só protege o que ela cobriu. Entre duas passadas do trabalho (uma hora, por padrão) há uma janela em que a corrente ainda não tem testemunha externa: quem reescrever tudo nela não é pego por âncora nenhuma. Diminua AUDIT_ANCHOR_INTERVAL_MINUTES se a janela importar, e lembre que ela só fecha de verdade se o cliente guardar as âncoras que recebe.
  • Não há selo temporal de terceiro. O createdAt é o relógio da nossa aplicação. A âncora prova ordem e conteúdo, não a hora exata perante um cartório.
  • Os marcadores de poda não são assinados. pruned_through_sequence e pruned_through_hash vivem na mesma tabela comum da cabeça. Quem os forja convence a verificação de que tudo até ali foi podado legitimamente — e as âncoras daquele trecho deixam de ter linha para conferir. A mitigação hoje é declarar: toda resposta do /verify traz os dois marcadores e anchorsCoveringPruned, então o auditor vê que eventos sumiram e quantas âncoras ficaram órfãs. Quem guarda as âncoras continua tendo com o que contestar. Assinar os marcadores está registrado como próximo passo.
  • As linhas anteriores a 22/09/2026 não são cobertas. Ficaram com sequence nulo, e GET /verify as conta em preChain. Encadeá-las retroativamente produziria uma prova falsa.
  • Um administrador da organização pode apagar a própria trilha. Com AUDIT_CONFIG_MANAGE, duas chamadas bastam: PUT /config/retention com retentionDays: 1 e POST /cleanup. O DELETE é físico, definitivo, e não deixa registro na própria trilha de que aconteceu. Esta é a limitação de segurança mais séria do building block, está repetida na §15 e precisa ser dita a qualquer cliente que compre trilha de auditoria como controle de compliance. A mitigação disponível hoje é operacional: conceder AUDIT_CONFIG_MANAGE a pouquíssimas contas, monitorar quedas bruscas em totalItems e manter cópia de segurança do banco com retenção própria. O encadeamento não conserta isso — o expurgo é legítimo por construção e poda um prefixo, anotando na cabeça até onde foi, de modo que a trilha restante continua válida. O que o cliente tem contra o expurgo abusivo são as âncoras que já recebeu: elas provam que existiam N linhas até tal hash, mesmo depois de elas sumirem daqui.
flowchart TD
  ADM["Conta com AUDIT_CONFIG_MANAGE"] --> P1["PUT /config/retention<br/>retentionDays: 1"]
  P1 --> P2["POST /cleanup"]
  P2 --> DEL["DELETE físico de quase toda a trilha da organização"]
  DEL --> NR["Sem confirmação, sem simulação, sem volta<br/>e sem registro na própria trilha"]
  MIT["Mitigação operacional"] -.-> M1["Conceder a pouquíssimas contas"]
  MIT -.-> M2["Monitorar quedas bruscas em totalItems"]
  MIT -.-> M3["Cópia de segurança do banco com retenção própria"]

A corrente prova integridade, não identidade

Esta distinção decide o que se pode afirmar numa auditoria, e ela não é detalhe técnico:

A corrente prova que ninguém editou a linha depois de gravada. Ela não prova que foi quem a linha diz que foi.

Quem publica o evento é quem define o ator. Em POST /events, o corpo manda: metadata.userId, metadata.actorType, metadata.ipAddress e metadata.userAgent entram na linha como vieram. E o carimbo automático de endereço sai do primeiro salto do x-forwarded-for, um cabeçalho que o cliente controla — quem chama a rota pode escrever o endereço que quiser ali. A única coisa que a plataforma impõe é a organização, que vem do token e nunca do corpo: um produtor não consegue escrever na trilha de outro cliente.

flowchart LR
  P["Produtor autenticado<br/>(painel, sistema parceiro)"] -->|"userId · actorType · ipAddress · userAgent"| R["POST /events"]
  T["Token do IAM"] -->|"organizationId — IMPOSTO"| R
  R --> ST(["iam-events"]) --> L["linha da trilha"]
  L --> C["corrente: ninguém edita depois"]
  L -.->|"o ator vale o que valer<br/>a autenticação do PRODUTOR"| C

A leitura prática: a confiança no ator de uma linha é a confiança no bloco que emitiu o evento. Evento publicado de dentro da plataforma (IAM, Customers, BaaS…) carrega o usuário que o IAM autenticou. Evento que entra por POST /events carrega o que o produtor afirmou — e o que se tem contra um produtor mentiroso é o controle de quem recebe a permissão AUDIT_EVENTS_WRITE, não a criptografia. Diga isso ao auditor antes que ele pergunte; a corrente não foi feita para responder a essa pergunta.

Enquadramento regulatório

NormaO que exigeComo o BB se posiciona
LGPD, art. 37Controlador e operador devem manter registro das operações de tratamento de dados pessoais, especialmente sob legítimo interesse. Não fixa formato nem prazo — o art. 40 delega o tempo de guarda à autoridade nacionalProduz o registro para as operações que os building blocks publicam, com autor, instante, recurso e diferenças, separado por organização, encadeado por hash e com carimbo assinado entregue ao cliente
LGPD, art. 16, IAutoriza conservar dado pessoal após o término do tratamento para cumprimento de obrigação legal ou regulatóriaÉ a base que permite manter a trilha mesmo depois de o titular exercer o direito de eliminação do art. 18, VI sobre o cadastro
Res. CMN 4.893/2021, art. 21, IInstituições financeiras devem instituir mecanismos de acompanhamento e controle incluindo "a definição de processos, testes e trilhas de auditoria"Contribui para o controle; não o satisfaz sozinho
Res. CMN 4.893/2021, art. 23, VIIIOs registros desses mecanismos ficam à disposição do Banco Central pelo prazo de cinco anosA retenção configurável vai a 3.650 dias, cobrindo os cinco anos com folga — mas o expurgo não é automático (§15)
Res. BCB 85/2021, arts. 21 e 23Mesma exigência, para instituições de pagamento, que a Res. CMN 4.893 exclui do escopoIdem

Atenção. Duas notas de precisão, porque erro de citação regulatória custa caro em proposta. A Circular BACEN 3.909/2018 trazia texto equivalente e teve os arts. 1º a 26 revogados pelo art. 26 da Resolução BCB 85/2021 — não a cite como norma vigente. E a Resolução Conjunta 6/2023 não é norma de Open Finance: ela trata de compartilhamento de indícios de fraude, e traz prazos ainda maiores (dez anos para os dados compartilhados, cinco para os registros dos mecanismos de controle).

O Audit Trail é matéria-prima de conformidade, não conformidade. A avaliação de suficiência, o mapeamento dos tratamentos e a política de retenção continuam sendo do encarregado de cada operação. O ponto que um auditor rigoroso questiona — "como você sabe que ninguém mexeu?" — agora tem resposta demonstrável (GET /verify, a âncora assinada e a exportação verificável offline), mas a resposta tem limites claros: sem WORM, sem selo temporal de terceiro, e sem cobertura das linhas anteriores a 22/09/2026. Leve os dois lados para a conversa antes que ele leve.

Não há certificação SOC 2, PCI-DSS ou ISO 27001 para este building block. Uma versão anterior desta documentação afirmava atendimento a LGPD, SOC 2 e PCI-DSS — essa afirmação não tem base e não deve ser repetida em proposta.

Retenção e eliminação

A retenção é declarada por organização e o expurgo é físico. Isso atende bem ao princípio de necessidade e ao art. 16 da LGPD, que trata do término do tratamento. Mas o expurgo não roda automaticamente — sem alguém chamar POST /cleanup, a retenção declarada é uma intenção, não um controle. Ver §15.


15

Limitações conhecidas

Bloqueia prometer trilha de auditoria hoje

LimitaçãoImpactoSituação
O consumidor continua desligado por padrão no códigoAUDIT_CONSUMER_ENABLED tem padrão false; os stacks publicados o ligam desde 10/09/2026, mas um ambiente montado à mão sem a variável grava nada e responde vazioConhecido — mitigado nos stacks
O expurgo não roda sozinhoRetentionCleanupJob.runForAllOrganizations() existe e não é chamado por nenhum agendador. A retenção só é aplicada quando alguém chama POST /cleanup, uma organização por vezNão implementado

Integridade e destruição da trilha

LimitaçãoImpactoSituação
Um administrador pode apagar a própria trilhaCom AUDIT_CONFIG_MANAGE, PUT /config/retention com 1 seguido de POST /cleanup remove fisicamente quase tudo. Não há confirmação, não há simulação e não há volta. O encadeamento não impede — a poda é legítima por construção; o que resta ao cliente são as âncoras que ele já recebeuLimitação séria — mitigação operacional + âncoras
Sem armazenamento WORMAs linhas vivem em tabela PostgreSQL comum. Quem tem acesso administrativo ao banco continua podendo alterar e apagar — a diferença, desde 22/09/2026, é que isso é detectável (GET /verify) e, se houver âncora cobrindo, indesmentívelPor design, com detecção
A janela entre âncoras não tem testemunhaO padrão é uma hora. Reescrita completa da corrente dentro da janela não é pega por âncora nenhuma — só pelo cliente que compare com o que já recebeuConhecido — ajustável por AUDIT_ANCHOR_INTERVAL_MINUTES
Sem selo temporal de terceirocreatedAt é o relógio da nossa aplicação. A âncora prova ordem e conteúdo, não a hora perante um cartórioNão implementado
Marcadores de poda sem assinaturapruned_through_sequence/pruned_through_hash estão numa tabela comum. Forjá-los faz a verificação engolir qualquer prefixo apagado, e as âncoras daquele trecho ficam sem linha para conferir. Mitigação: o /verify declara os dois marcadores e anchorsCoveringPruned em toda resposta, e as âncoras que o cliente guardou continuam contradizendo a versão podadaConhecido — assinar os marcadores é o próximo passo
O ator não é provado, só registradoPOST /events aceita userId, actorType, ipAddress e userAgent do corpo, e o carimbo automático de IP usa o primeiro salto do x-forwarded-for, controlado por quem chama. A corrente prova que a linha não mudou depois; não prova que foi quem ela diz que foi — ver §14Por design, com implicação de confiança
As linhas anteriores a 22/09/2026 não são verificáveisFicaram com sequence nulo e aparecem como preChain no /verify. Encadeá-las retroativamente seria produzir prova falsaPor design
Sem rotação de chave de assinatura pela APIGET /keys lista; aposentar uma chave e emitir outra exige código. E trocar AUDIT_TRAIL_SIGNING_MASTER_KEY sem recifrar as privadas existentes impede novas âncoras (as antigas seguem verificáveis)Não implementado

Especificado, não implementado

LimitaçãoImpactoSituação
Eventos de segurança não chegam à trilhaAuditAction declara LOGIN, LOGOUT, ACCESS_DENIED, TOKEN_ISSUED, TOKEN_FAILED e RATE_LIMITED, e o mapa de eventos prevê security.*. Mas o logSecurityEvent escreve apenas no log de aplicação e nada publica no fluxo Redis. Login, logout e acesso negado não aparecem na trilhaEspecificado, não implementado
ipAddress e userAgent só vêm de POST /eventsA rota de ingestão carimba o primeiro salto do x-forwarded-for e o user-agent, e o consumidor os grava quando o evento os traz na metadata. Evento publicado de dentro de um bloco continua sem requisição à mão — e continua nuloParcialmente implementado

Escolhas de projeto

LimitaçãoImpactoSituação
A cobertura depende de cada building block publicarNão há middleware, gatilho nem interceptador que audite sozinho. Operação sem chamada de publicação não aparece, e a trilha não tem como sinalizar a ausênciaPor design
Evento sem organizationId é descartado em silêncioO consumidor confirma a mensagem e não grava nada. Sem erro, sem métrica dedicadaPor design, com efeito colateral
Sem busca textualOs filtros são igualdade exata mais período. Não há busca livre em changes nem em metadataPor design
Sem alerta, correlação ou detecçãoO Audit Trail registra e devolve. Não avisa ninguém, não correlaciona e não detecta padrãoPor design — é papel de SIEM
Sem dado pessoal mascaradoA lista de campos mascarados cobre credencial, não dado pessoal. CPF, nome, e-mail e telefone ficam em texto em changesPor design, com implicação de acesso (§14)

Inconsistências e limites conhecidos

LimitaçãoImpactoSituação
Mensagem descartada após três entregasAcima de três tentativas a mensagem é confirmada e some. O código chama de fila de mensagens mortas, mas não existe fila — a trilha perde o evento, com um aviso no logConhecido
links.self aponta para rota inexistenteCada linha traz links.self para /audit-trail/api/v1/logs/{id}, e não há endpoint de busca por identificador. Seguir o link devolve 404Inconsistência conhecida
A linha do tempo por recurso não paginaGET /logs/resource/:type/:id devolve todas as linhas em um documento, sem limite. Recurso com histórico longo gera resposta grandeConhecido
resourceId pode capturar o campo erradoÉ o primeiro identificador encontrado numa ordem fixa. Carga que traga organizationId antes do identificador próprio grava a organização como recurso. baas.* e biometrics.* ganharam lista própria em 22/09/2026 (e antes disso gravaram a organização); os demais seguem na ordem genéricaConhecido, mitigado nos dois casos medidos
A ingestão externa não tem chave de idempotênciaPOST /events devolve o id do fluxo como recibo; um produtor que repete a chamada após falha de rede grava a linha duas vezes. O painel só chama uma vez por passo de workflowConhecido
A sonda de saúde não reflete o estado realGET /health responde ok com o Postgres fora do ar e com o consumidor desligadoConhecido

Roadmap

LimitaçãoImpactoSituação
Exportação só em NDJSONGET /export transmite NDJSON verificável offline. CSV não entra: perderia o aninhamento que o hash cobre e deixaria de ser verificávelPor design
Sem métrica de linhas gravadasNão há contador de eventos registrados nem de eventos descartados. Detectar que a trilha parou exige consultar a própria trilha — ou olhar a cabeça da corrente, que agora existeRoadmap
A escrita ficou mais caraCada linha passa por uma transação com trava por organização, em vez de um INSERT solto. Escritas da MESMA organização serializam. Medido em teste de integração: 40 escritas simultâneas de uma organização, sequência sem buraco, sob um segundoConsequência aceita do encadeamento

16

Perguntas frequentes

O Audit Trail captura tudo automaticamente?

Não, e essa é a pergunta mais importante deste documento. Cada building block publica explicitamente os eventos dele — a chamada está escrita linha a linha em cada serviço. Do lado do Audit Trail, o consumo é automático: qualquer evento publicado no fluxo é registrado sem alteração aqui. Então a resposta honesta é: automático para o que a plataforma publica, e cego para o que ela não publica. Vender como "auditoria automática de tudo" não sobrevive a uma auditoria técnica.

Minha trilha está vazia. O que aconteceu?

Quase certamente o consumidor está desligado. AUDIT_CONSUMER_ENABLED tem padrão false e não é definido nos stacks de staging nem de produção; em modo monolito o consumidor nem chega a ser iniciado. As rotas de leitura respondem 200 com lista vazia, o que parece uma trilha sem atividade. Siga a receita de diagnóstico da §11 antes de procurar outra causa.

O log é imutável? Alguém pode apagar?

Pela API, nenhuma linha pode ser alterada e nenhuma linha individual pode ser apagada — não existe rota para isso. Direto no banco, ainda pode: não há WORM. A diferença desde 22/09/2026 é que não é mais silencioso. Cada linha é encadeada à anterior por hash, GET /verify aponta a primeira sequência quebrada, e a cabeça da corrente é assinada e entregue ao cliente por webhook — quem reescrever a corrente inteira aqui dentro é denunciado por qualquer âncora que o cliente tenha guardado. O que continua valendo: quem tem AUDIT_CONFIG_MANAGE pode reduzir a retenção para um dia e expurgar a própria trilha, e a janela entre duas âncoras (uma hora, por padrão) fica sem testemunha externa. Se o requisito do cliente é WORM com selo temporal de cartório, este bloco não é isso — e a §14 explica exatamente o que ele é.

Como provo a um auditor que a trilha não foi adulterada?

Três passos, e nenhum deles pede que ele confie em nós. GET /verify sem intervalo recalcula a corrente inteira e responde valid, quantas linhas conferiu e, se algo quebrou, em qual sequência e por quê. GET /export entrega o arquivo NDJSON com os campos exatos que entram no hash. E a última linha do arquivo traz a âncora assinada em Ed25519 mais a chave pública, que ele confere sozinho com o algoritmo publicado na §11 — inclusive contra as âncoras que o próprio cliente recebeu por webhook, que são a cópia que nós não alcançamos.

Login e tentativa de acesso negado aparecem na trilha?

Não. As ações existem na enumeração e o mapa de eventos as prevê, mas o registro de evento de segurança hoje vai apenas para o log de aplicação — nada é publicado no fluxo que o Audit Trail consome. Para investigar autenticação, a fonte é o log do IAM, não a trilha.

O que é preChain na resposta do /verify?

São as linhas gravadas antes de o encadeamento existir (22/09/2026): ficaram com sequence nulo e não têm hash para conferir. Elas não foram reescritas de propósito — encadear o passado retroativamente produziria uma prova que parece forte e não é. valid: true com preChain: 4120 quer dizer "daqui para a frente eu provo; para trás, não".

Consigo saber de qual IP veio a alteração?

Depende de quem publicou. Evento que entra por POST /events traz o endereço: a rota carimba o primeiro salto do x-forwarded-for e o user-agent quando o corpo não os informa, e o produtor que sabe quem é o cliente final dele pode mandar os dele. Evento publicado de dentro de um building block, não: não há requisição à mão, e as colunas seguem nulas.

Como faço para exportar a trilha para um auditor?

GET /export?from=&to=&format=ndjson, que transmite em fluxo a trilha encadeada com a âncora assinada na última linha — receita e verificador offline na §11. O token expira em uma hora, então extração muito longa precisa renovar. Linhas pré-corrente não saem por ali (a exportação só transmite o que é verificável); para elas, é paginar GET /logs.

Quanto tempo a trilha é guardada?

O que a organização declarar, de 1 a 3.650 dias, com padrão de 365. Mas atenção: declarar não apaga. O expurgo só acontece quando alguém chama POST /cleanup, e não há agendador fazendo isso. Na prática, hoje a trilha cresce até alguém executar o expurgo manualmente.

A trilha guarda dado pessoal?

Guarda. O campo changes carrega o antes e o depois do que mudou, e quando o recurso é uma pessoa, isso inclui CPF, nome, e-mail e telefone em texto. O mascaramento automático cobre senha, segredo, token e chave de API — não cobre dado pessoal. Conceder AUDIT_LOGS_READ é conceder acesso a esse conteúdo, inclusive para quem não tem permissão no building block de origem.

Isso me deixa em conformidade com a LGPD?

Não sozinho. O art. 37 da LGPD exige registro das operações de tratamento, e este building block produz esse registro para as operações que os building blocks publicam. A avaliação de suficiência, o mapeamento dos tratamentos, a base legal e a política de retenção continuam sendo do encarregado da sua operação. E há a ressalva da imutabilidade: um auditor rigoroso vai perguntar como você garante que a trilha não foi adulterada, e a resposta honesta hoje está na §14.

Se um cliente pedir a eliminação dos dados dele, tenho que apagar a trilha também?

Normalmente não, e apagar pode ser o erro. O direito de eliminação do art. 18, VI da LGPD tem exceção expressa no art. 16, que autoriza a conservação para cumprimento de obrigação legal ou regulatória. Para instituição regulada pelo BACEN, os cinco anos do art. 23 da Resolução CMN 4.893/2021 são exatamente essa obrigação. A leitura prática é: elimine o cadastro operacional, preserve a trilha pelo prazo regulatório, e documente a base legal da conservação. A decisão é do seu encarregado, não deste documento.

A trilha atende à exigência de cinco anos do BACEN?

Tecnicamente a retenção vai a 3.650 dias, o dobro do exigido, e desde 22/09/2026 há evidência de integridade (corrente + âncora assinada) para mostrar ao supervisor. Operacionalmente ainda falta: o expurgo é manual e o consumidor precisa estar ligado no ambiente. Antes de afirmar atendimento ao art. 21, I da Resolução CMN 4.893/2021, resolva os itens da §15 marcados como bloqueantes.

Qual a diferença entre o Audit Trail e o Webhooks Engine?

Os dois leem o mesmo fluxo Redis, cada um no próprio grupo de consumidor. O Audit Trail guarda o evento para consulta posterior. O Webhooks Engine entrega o evento a um sistema externo, com nova tentativa e assinatura. Ligar ou desligar um não afeta o outro.

Audit TrailWebhooks Engine
Grupo de consumidoraudit-trail-consumerswebhook-consumers
O que faz com o eventoGuarda para consulta posteriorEntrega a um sistema externo
Recursos própriosFiltros, paginação, retenção e expurgoNova tentativa e assinatura da entrega
Depende do outro?NãoNão

Posso registrar um evento próprio da minha aplicação?

De dentro deste código, publicando um evento de domínio no fluxo com organizationId na metadata (sem ele o consumidor descarta em silêncio). De fora, por POST /audit-trail/api/v1/events com AUDIT_EVENTS_WRITE: o serviço carimba a organização do token e publica o mesmo evento no fluxo. Nos dois casos o type segue bloco.recurso.acao.


Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md