lgpd-audit-logging

Exact captured content · path skills/lgpd-audit-logging/SKILL.md · sha256 5fe42677d4fb75f2… · revision 65e625daf56f84a2c8d9b8b063d1d70481abba3d

Download the exact captured file

---
name: lgpd-audit-logging
description: Design and implement tamper-evident, transactionally serialized audit logging as a recommended engineering control for LGPD accountability (Art. 6, X) and security (Art. 46). Outputs Prisma schema, concurrency-safe hash-chain writer, DB write-protection triggers, and external WORM/SIEM anchoring verification.
---

# Audit Logging — Trilha de Auditoria Tamper-Evident

Controle de engenharia voltado a sustentar **responsabilização e prestação de contas (`Art. 6º, X`)** e **segurança da informação (`Art. 46`)**.

> **Distinção normativa importante:**
> 1. **A LGPD não exige expressamente o uso de *hash chain*.** A lei exige medidas técnicas e administrativas aptas a proteger os dados (`Art. 46`) e demonstração de eficácia (`Art. 6º, X`). O encadeamento criptográfico (*hash chain*) é classificado aqui como **controle técnico recomendado** para detecção de adulteração (*tamper-evidence*), não como imposição literal do texto legal.
> 2. **Prazo de retenção:** o prazo legal mínimo de **5 anos** do **Art. 10 da Resolução CD/ANPD nº 15/2024** refere-se especificamente ao **registro de incidentes de segurança com dados pessoais**. Para logs operacionais de auditoria (acessos administrativos, exportações, DSAR, consentimento), defina retenção proporcional aos prazos prescricionais e de fiscalização aplicáveis (ex.: 6 meses mínimos do Art. 15 do Marco Civil para logs de acesso a aplicações; 3 a 5 anos para trilhas probatórias de DSAR/consentimento sob Art. 6º, X e Res. 4/2023).

## Por que uma *hash chain* sozinha NÃO é imutável

Uma cadeia de hashes armazenada apenas na mesma tabela PostgreSQL detecta edições pontuais ingênuas, mas **sofre duas falhas clássicas se mal implementada**:
1. **Condição de corrida (*race condition*)**: duas requisições paralelas que leem o último hash fora de uma transação serializada gravam o **mesmo `prevHash`**, bifurcando e quebrando a cadeia em produção.
2. **Reescrita privilegiada**: um invasor ou administrador malicioso com permissão de `UPDATE`/`DELETE` no banco pode alterar um registro antigo e **recalcular todos os hashes subsequentes** em segundos.

Para que a trilha seja confiável de verdade, combine **quatro camadas**:
1. **Serialização transacional + sequência monotônica (`seq BigInt`)**: use `pg_advisory_xact_lock` dentro de `db.$transaction(...)` e ordene por `seq` (nunca apenas por `timestamp`, que pode empatar no mesmo milissegundo).
2. **Restrição de privilégios e triggers no PostgreSQL**: a role da aplicação deve ter apenas `SELECT, INSERT` (`REVOKE UPDATE, DELETE, TRUNCATE`) + trigger bloqueando mutações.
3. **Mapeamento explícito de colunas**: nunca faça spread (`...entry`) repassando objetos `Request` ou payloads brutos para o Prisma, e extraia apenas o primeiro IP válido de `x-forwarded-for` para não quebrar colunas `@db.Inet`.
4. **Ancoragem externa periódica (WORM / SIEM)**: publique periodicamente (ex.: a cada hora/dia) o par `(seq, selfHash)` mais recente em destino externo imutável (S3 Object Lock em modo Compliance, CloudWatch Logs / GCP Cloud Logging em conta segregada) e valide-o em `verifyAuditChain()`.

## Artefatos de referência prontos e testados

- **Schema Prisma**: [`assets/audit-log.prisma`](assets/audit-log.prisma)
- **Implementação TypeScript serializada + verificador**: [`assets/audit-log.ts`](assets/audit-log.ts)

## Uso recomendado em rotas críticas

```ts
import { logAudit, verifyAuditChain } from "@/lib/privacy/audit-log";

await logAudit(prisma, {
  actorId: session.user.id,
  actorType: "USER",
  action: "DSAR_EXPORT_COMPLETED",
  resource: `User:${session.user.id}`,
  subjectId: session.user.id,
  legalBasis: "ART_18_II",
  purpose: "subject_data_export",
  // NUNCA passe PII em claro — apenas metadados redigidos ou hashes
  redactedMetadata: { format: "json", bundleSha256: bundleHash },
  req,
});
```

## Eventos prioritários para registrar (sem PII em claro)

- Autenticação administrativa, elevação de privilégio e mudanças de RBAC
- Leitura/exportação administrativa de dados pessoais ou sensíveis de terceiros
- Operações do ledger de consentimento (`GRANTED`, `REVOKED`, `SUPERSEDED`)
- Ciclo completo de DSAR (recebimento, verificação proporcional de identidade, atendimento, eventual recusa fundamentada)
- Execução de jobs de retenção, anonimização e *crypto-shredding*

## Proteção de banco + Ancoragem externa

1. Aplique na tabela `"AuditLogEntry"` a mesma trigger de bloqueio de `UPDATE`, `DELETE` e `TRUNCATE` (ver `lgpd-consent-schema/assets/consent-append-only.sql`) e revogue permissões destrutivas da role de aplicação.
2. Agende job diário que:
   - Executa `verifyAuditChain(entries, lastExternalAnchor)`;
   - Grava o novo `(seq, selfHash)` em bucket S3 Object Lock (WORM) ou SIEM segregado;
   - Dispara alerta imediato para Segurança e Encarregado em caso de divergência.

## Status update

```markdown
## F8 / L8b — Audit logging ✓
- Modelo `AuditLogEntry` com `seq` monotônico validado
- `logAudit()` serializado com `pg_advisory_xact_lock` e sanitização de IP
- Trigger append-only + revogação de `UPDATE/DELETE` configurados
- Verificação periódica `verifyAuditChain()` + âncora externa configuradas
```