Caramel Integrations SQS Audit Log

Biblioteca de integração Caramel para registro de Audit Logs usando AWS SQS para processamento assíncrono.

Características

• 📝 Apenas registro de audit logs (sem consultas)
• 📨 Integração com AWS SQS para processamento assíncrono
• 🏗️ Arquitetura Caramel com injeção de dependências (InversifyJS)
• 📦 TypeScript com tipos completos
• 🔄 Versionamento (suporta v1)
• 🎯 Enums tipados para actions e scopes

Instalação

npm install @aprova-digital/caramel-integrations-sqs-audit-log

Dependências

npm install @aprova-digital/caramel @aprova-digital/caramel-settings @aprova-digital/caramel-integrations-sqs inversify

Uso

1. Configuração da Instrução

import { Builder } from "@aprova-digital/caramel";
import { AuditLogIntegrationsInstruction } from "@aprova-digital/caramel-integrations-sqs-audit-log";

const builder = new Builder();
builder.addInstruction(AuditLogIntegrationsInstruction);
await builder.build();

2. Uso da Integração

import { 
  AuditLogV1IntegrationSqs,
  RegisterAuditLogInput,
  AuditLogAction,
  AuditLogScope
} from "@aprova-digital/caramel-integrations-sqs-audit-log";

// Obter a integração do container
const container = builder.getContainer();
const auditLogIntegration = container.get(AuditLogV1IntegrationSqs);

// Preparar os dados do audit log
const auditLogData: RegisterAuditLogInput = {
  userId: "user-123",
  organizationId: "org-456",
  action: AuditLogAction.PERMISSION_GROUP_CREATE,
  scope: AuditLogScope.PERMISSION_GROUP,
  metadata: {
    groupName: "Administradores",
    permissions: ["read", "write", "delete"],
  },
  ip: "192.168.1.1"
};

// Registrar o audit log (envia para a fila SQS)
await auditLogIntegration.registerAuditLog(JSON.stringify(auditLogData));

Estrutura de Dados

RegisterAuditLogInput

interface RegisterAuditLogInput {
  userId: string;              // ID do usuário que realizou a ação
  organizationId: string;      // ID da organização
  action: AuditLogAction;      // Ação realizada (enum)
  scope: AuditLogScope;        // Escopo da ação (enum)
  metadata: Record<string, any>;  // Metadados da ação
  ip: string;                  // Endereço IP do usuário
}

AuditLogAction (Enum)

enum AuditLogAction {
  PERMISSION_GROUP_UPDATE = "permission_group:update",
  PERMISSION_GROUP_CREATE = "permission_group:create",
  PERMISSION_GROUP_DELETE = "permission_group:delete",
  PERMISSION_GROUP_ADD_USER = "permission_group:add_user",
  PERMISSION_GROUP_REMOVE_USER = "permission_group:remove_user",
  HUB_API_CREATE = "hub_api:create",
  HUB_API_DELETE = "hub_api:delete",
  HUB_API_REQUEST_EXECUTED = "hub_api:request_executed",
}

AuditLogScope (Enum)

enum AuditLogScope {
  AUTHORIZATION = "authorization",
  PERMISSION_GROUP = "permission_group",
  HUB_API = "hub_api",
}

API da Integração

registerAuditLog(message: string): Promise<void>

Registra um audit log enviando para a fila SQS configurada.

Parâmetros:

• message: String JSON com os dados do audit log

Exemplo:

const auditLog: RegisterAuditLogInput = {
  userId: "user-123",
  organizationId: "org-456",
  action: AuditLogAction.PERMISSION_GROUP_ADD_USER,
  scope: AuditLogScope.PERMISSION_GROUP,
  metadata: {
    groupId: "group-789",
    addedUserId: "user-999",
  },
  ip: "10.0.0.1"
};

await auditLogIntegration.registerAuditLog(JSON.stringify(auditLog));

Configuração

A integração utiliza as seguintes configurações do Settings:

• AUDIT_LOG_QUEUE_NAME: Nome da fila SQS onde os audit logs serão enviados

Certifique-se de configurar essas variáveis de ambiente no seu projeto.

Integração com SQS

Todos os audit logs registrados são automaticamente enviados para a fila SQS configurada em AUDIT_LOG_QUEUE_NAME para processamento assíncrono.

A biblioteca utiliza o @aprova-digital/caramel-integrations-sqs para gerenciar a comunicação com AWS SQS.

Desenvolvimento

Build

npm run build

Estrutura do Projeto

src/
├── audit-log.integrations.sqs.ts         # Classe principal de integração
├── audit-log.integrations.instruction.ts # Instrução Caramel
├── v1/
│   ├── audit-log.v1.integration.sqs.ts   # Implementação v1
│   ├── dto/
│   │   └── register-audit-log.input.ts   # DTO de registro
│   └── enums/
│       ├── audit-log-actions.enum.ts     # Enum de ações
│       └── audit-log-scopes.enum.ts      # Enum de escopos
└── index.ts                               # Exports públicos

Exemplo Completo

import { Builder } from "@aprova-digital/caramel";
import { 
  AuditLogIntegrationsInstruction,
  AuditLogV1IntegrationSqs,
  RegisterAuditLogInput,
  AuditLogAction,
  AuditLogScope
} from "@aprova-digital/caramel-integrations-sqs-audit-log";

// 1. Configurar o builder
const builder = new Builder();
builder.addInstruction(AuditLogIntegrationsInstruction);
await builder.build();

// 2. Obter a integração
const container = builder.getContainer();
const auditLog = container.get(AuditLogV1IntegrationSqs);

// 3. Registrar diferentes tipos de audit logs

// Exemplo 1: Criação de grupo de permissões
await auditLog.registerAuditLog(JSON.stringify({
  userId: "user-123",
  organizationId: "org-456",
  action: AuditLogAction.PERMISSION_GROUP_CREATE,
  scope: AuditLogScope.PERMISSION_GROUP,
  metadata: {
    groupName: "Administradores",
    permissions: ["admin:read", "admin:write"],
  },
  ip: "192.168.1.1"
}));

// Exemplo 2: Adição de usuário a grupo
await auditLog.registerAuditLog(JSON.stringify({
  userId: "user-123",
  organizationId: "org-456",
  action: AuditLogAction.PERMISSION_GROUP_ADD_USER,
  scope: AuditLogScope.PERMISSION_GROUP,
  metadata: {
    groupId: "group-789",
    addedUserId: "user-999",
    addedUserEmail: "[email protected]",
  },
  ip: "192.168.1.1"
}));

// Exemplo 3: Atualização de grupo
await auditLog.registerAuditLog(JSON.stringify({
  userId: "user-123",
  organizationId: "org-456",
  action: AuditLogAction.PERMISSION_GROUP_UPDATE,
  scope: AuditLogScope.PERMISSION_GROUP,
  metadata: {
    groupId: "group-789",
    changes: {
      before: { name: "Admin" },
      after: { name: "Administradores" },
    },
  },
  ip: "192.168.1.1"
}));

Observações

• Esta biblioteca é somente para registro de audit logs. Não há funcionalidade de consulta ou listagem.
• Os audit logs são enviados de forma assíncrona para a fila SQS.
• O processamento e armazenamento dos logs deve ser implementado por um consumidor da fila SQS.
• A biblioteca segue o padrão caramel-integrations, focando apenas na integração com serviços externos (neste caso, SQS).

Licença

ISC

Autor

Aprova Digital