Audit Trail

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.

Está em beta. As duas tabelas, as seis rotas (cinco de leitura e configuração, uma de ingestão para produtores externos), o consumidor de eventos 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"]

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.

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.

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.

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.

Tabela comparativa

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

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.

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

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:

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.

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.

Este é o building block em que a arquitetura importa mais que a lista de rotas. Ele tem dois 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); e um de leitura, síncrono, com cinco rotas.

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]"]
  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 --> DB

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"]
  R1 --> SV["AuditLogService · AuditConfigService<br/>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.

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.
• 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: mais de 3 entregas — XACK e a mensagem some
  Descartada --> [*]

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.

Glossário

Modelo de dados

Schema audit no PostgreSQL. 2 modelos.

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"
    string ip_address "sempre nulo hoje"
    string user_agent "sempre nulo hoje"
    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) e eventType. 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, deletedAt, campo de assinatura, encadeamento com o registro anterior. AuditLog é criado e nunca atualizado. As implicações estão na §14.

Enumerações

Como um evento vira uma linha da trilha

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

{
  "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"]

Ciclo de vida de uma linha da trilha

stateDiagram-v2
  [*] --> Gravada: evento consumido
  Gravada --> Expurgada: POST /cleanup com AUDIT_CONFIG_MANAGE remove createdAt anterior a hoje menos retentionDays
  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. Definitivo.
    Sem cópia, sem arquivamento,
    sem registro de que o expurgo ocorreu.
    A linha deixa de existir.
  end note

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

Todas as 6 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

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

Corpo JSON:API: { "data": { "type": "audit-events", "attributes": { "type": "credit.operation.created", "payload": {…}, "metadata": { "timestamp"?, "correlationId"?, "userId"? } } } } ou attributes.events[] com a mesma forma. 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.

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

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

Saúde do serviço

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

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

Resposta 200

{
  "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

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.

Resposta 200

{
  "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", "...": "..." } }
  ]
}

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:

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

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

Depois de configurada:

{
  "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:

{ "data": { "attributes": { "retentionDays": 1825 } } }

{ "data": { "attributes": { "retentionDays": 1825 } } }

{ "retentionDays": 1825 }

{ "retentionDays": 1825 }

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

POST /audit-trail/api/v1/cleanup

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

Resposta 200

{
  "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
    }
  }
}

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

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.

2. Ver a retenção vigente

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

{ "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

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]'

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.

# 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:

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

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'

"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?

Investigar "quem alterou este registro"

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

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"]

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.

• Não há endpoint de exportação. Paginar é o único caminho, e o máximo é 100 por página. Ver §15.
• 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.

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/>Procure Message exceeded max retries no log"]
  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:

docker service logs <stack>_audit-trail 2>&1 | grep -i "audit consumer"

docker service logs <stack>_audit-trail 2>&1 | grep -i "audit consumer"

Audit consumer started successfully

Audit consumer started successfully

Se em vez disso aparecer Audit consumer is disabled (AUDIT_CONSUMER_ENABLED=false), pare por aqui: nada será gravado.

2. O evento chegou ao fluxo Redis?

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.

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?

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. Procure Message exceeded max retries no log do audit-trail.

Definir retenção diferente por cliente

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

# 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'

{ "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

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

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

365

365

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

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

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'

{ "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.

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"]

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.

Variáveis de ambiente

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.

Dependências de infraestrutura

Comportamento do consumidor

Limites

Catálogo de erros

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 gera Message exceeded max retries — vale um alerta, porque é perda silenciosa de 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.

Isolamento entre organizações

O organizationId é claim assinado do JWT. As seis 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, deleteExpired e a busca de configuração incluem a organização na cláusula where. 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:

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:

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? Parcialmente — e a diferença importa

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.

O que não é garantido:

• Não há imutabilidade criptográfica. Nenhuma assinatura, nenhum encadeamento com o registro anterior, nenhum selo temporal. Uma linha alterada direto no banco é indetectável pela aplicação.
• Não há armazenamento WORM. As linhas ficam numa tabela PostgreSQL comum. Quem tem acesso administrativo ao banco pode UPDATE e DELETE à vontade, e isso não aparece na trilha.
• 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.

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"]

Enquadramento regulatório

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. E a ausência de imutabilidade forte, descrita acima, é justamente o ponto que um auditor rigoroso vai questionar — leve isso 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.

Bloqueia prometer trilha de auditoria hoje

Integridade e destruição da trilha

Especificado, não implementado

Escolhas de projeto

Inconsistências e limites conhecidos

Roadmap

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. Mas quem tem AUDIT_CONFIG_MANAGE pode reduzir a retenção para um dia e executar o expurgo, apagando fisicamente quase toda a trilha da própria organização em duas chamadas, sem deixar registro. E não há assinatura, encadeamento nem armazenamento WORM: quem tem acesso administrativo ao banco altera sem rastro. Se o seu requisito é imutabilidade forte, este building block não atende hoje. Diga isso ao cliente antes de assinar.

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.

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

Não. As colunas ipAddress e userAgent existem na tabela e nunca são preenchidas por este caminho, porque o evento de domínio não carrega essa informação. Vêm sempre nulas.

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

Paginando GET /logs de 100 em 100 com filtro de período — há um script pronto na §11. Não existe rota de exportação, e o token expira em uma hora, então extração longa precisa renovar no meio.

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. Operacionalmente, hoje, não: o expurgo é manual, o consumidor está desligado nos ambientes publicados, e não há imutabilidade forte. Antes de afirmar atendimento ao art. 21, I da Resolução CMN 4.893/2021, resolva os três 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.

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}