Segurança - Lerian

O Matcher implementa controles de segurança abrangentes para proteger dados de reconciliação financeira. Este guia aborda autenticação, autorização, isolamento de tenant, criptografia e recursos de conformidade.

Visão geral

A arquitetura de segurança do Matcher é construída em várias camadas. Toda requisição de API passa por múltiplos pontos de verificação de segurança antes de acessar seus dados.

Primeiro, o TLS criptografa a conexão.

Em seguida, a autenticação verifica quem você é:

O isolamento de tenant garante que você veja apenas seus próprios dados.
O RBAC verifica se você tem permissão para realizar a ação.

Por fim, o sistema registra tudo para fins de auditoria.

Proteção por camadas

Camada	Proteção
Transporte	Criptografia TLS 1.2+
Autenticação	Tokens JWT via lib-auth
Isolamento de Tenant	Schema-por-tenant PostgreSQL
Autorização	Controle de acesso baseado em funções
Auditoria	Logs imutáveis somente-anexação
Armazenamento	Criptografia em repouso

Autenticação

O Matcher usa a biblioteca compartilhada lib-auth (v2) para autenticação, suportando controle de acesso baseado em JWT com assinatura HMAC.

Configuração

Três variáveis de ambiente controlam a autenticação:

Variável	Obrigatória	Descrição
`AUTH_ENABLED`	Sim	Habilitar ou desabilitar autenticação (`true`/`false`)
`AUTH_SERVICE_ADDRESS`	Quando auth habilitado	Endereço do serviço de autorização externo
`AUTH_JWT_SECRET`	Quando auth habilitado	Segredo compartilhado para verificação de assinatura de token HMAC

Quando AUTH_ENABLED=false (apenas desenvolvimento), o Matcher usa um ID de tenant padrão (11111111-1111-1111-1111-111111111111) e ignora as verificações de autorização.

Estrutura do token JWT

O Matcher valida JWTs assinados com algoritmos HMAC (HS256, HS384, HS512). O token deve incluir claims de identificação do tenant:

{
  "sub": "user_123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "tenant_slug": "acme-corp",
  "iat": 1705749600,
  "exp": 1705753200,
  "nbf": 1705749600
}

Claim	Obrigatório	Descrição
`tenant_id` ou `tenantId`	Sim	UUID do tenant para isolamento de schema
`tenant_slug` ou `tenantSlug`	Não	Identificador legível do tenant
`sub`	Não	ID do usuário (usado para log de auditoria)
`exp`	Sim	Tempo de expiração do token
`nbf`	Não	Tempo not-before (token é inválido antes deste momento)

Headers obrigatórios

Todas as requisições de API devem incluir autenticação:

curl -X GET "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN"

Validação de token

O Matcher valida tokens em cada requisição:

Verificação de assinatura: Valida a assinatura HMAC usando o segredo compartilhado configurado
Verificação de expiração: Rejeita tokens expirados (claim exp)
Verificação de not-before: Rejeita tokens usados antes do tempo nbf
Extração de tenant: Extrai tenant_id para isolamento de schema

Autorização (RBAC)

O controle de acesso baseado em funções protege todos os endpoints da API. O Matcher delega a autorização a um serviço de autenticação externo via lib-auth. As permissões são granulares e seguem o padrão resource:sub-resource:action.

Estrutura de permissão

<resource>:<sub-resource>:<action>

Exemplos:

configuration:context:create — Criar contextos de reconciliação
matching:job:run — Executar jobs de correspondência
exception:exception:resolve — Resolver exceções

Lista completa de permissões

O Matcher define seis domínios de recursos. Cada endpoint requer uma permissão específica verificada contra o serviço de autorização externo.

Configuração

Permissão	Descrição
`configuration:context:create`	Criar contextos de reconciliação
`configuration:context:read`	Visualizar contextos
`configuration:context:update`	Atualizar contextos
`configuration:context:delete`	Excluir contextos
`configuration:source:create`	Criar fontes de dados
`configuration:source:read`	Visualizar configuração de fonte
`configuration:source:update`	Modificar configurações de fonte
`configuration:source:delete`	Remover fontes de dados
`configuration:field-map:create`	Criar mapeamentos de campo
`configuration:field-map:read`	Visualizar mapeamentos de campo
`configuration:field-map:update`	Atualizar mapeamentos de campo
`configuration:field-map:delete`	Excluir mapeamentos de campo
`configuration:rule:create`	Criar regras de correspondência
`configuration:rule:read`	Visualizar regras de correspondência
`configuration:rule:update`	Atualizar regras de correspondência
`configuration:rule:delete`	Excluir regras de correspondência
`configuration:fee-schedule:create`	Criar agendamentos de tarifas
`configuration:fee-schedule:read`	Visualizar agendamentos de tarifas
`configuration:fee-schedule:update`	Atualizar agendamentos de tarifas
`configuration:fee-schedule:delete`	Excluir agendamentos de tarifas
`configuration:schedule:create`	Criar agendamentos
`configuration:schedule:read`	Visualizar agendamentos
`configuration:schedule:update`	Atualizar agendamentos
`configuration:schedule:delete`	Excluir agendamentos

Ingestão

Permissão	Descrição
`ingestion:import:create`	Fazer upload de arquivos de transação
`ingestion:job:read`	Visualizar jobs de importação e detalhes de transação
`ingestion:transaction:ignore`	Marcar transações como ignoradas
`ingestion:transaction:search`	Pesquisar transações

Correspondência

Permissão	Descrição
`matching:job:run`	Executar ciclos de correspondência
`matching:job:read`	Visualizar resultados de correspondência e grupos
`matching:job:delete`	Excluir grupos de correspondência (desfazer correspondência)
`matching:adjustment:create`	Criar lançamentos de ajuste

Exceção

Permissão	Descrição
`exception:exception:read`	Visualizar exceções e histórico
`exception:exception:resolve`	Forçar correspondência ou ajustar lançamentos
`exception:exception:dispatch`	Despachar exceções para sistemas externos
`exception:callback:process`	Processar callbacks de webhook externo
`exception:dispute:read`	Visualizar disputas
`exception:dispute:write`	Criar disputas, encerrar disputas, enviar evidências
`exception:comment:write`	Adicionar ou excluir comentários em exceções

Governança

Permissão	Descrição
`governance:audit:read`	Visualizar logs de auditoria
`governance:archive:read`	Visualizar e baixar arquivos
`governance:actor-mapping:read`	Visualizar mapeamentos de ator
`governance:actor-mapping:write`	Criar ou atualizar mapeamentos de ator
`governance:actor-mapping:delete`	Excluir mapeamentos de ator

Relatórios

Permissão	Descrição
`reporting:dashboard:read`	Acessar análises e métricas do dashboard
`reporting:export:read`	Visualizar e exportar relatórios (correspondidos, não correspondidos, resumo, variância)
`reporting:export-job:write`	Criar e cancelar jobs de exportação
`reporting:export-job:read`	Visualizar status de jobs de exportação e baixar exportações

Gerenciamento de funções

O serviço de autorização externo gerencia as funções, não o próprio Matcher. Configure as funções e suas permissões associadas no seu provedor de identidade ou serviço de autenticação. O Matcher verifica as permissões em cada requisição chamando o serviço de autenticação com o recurso e a ação necessários.

Isolamento de tenant

O Matcher usa isolamento schema-por-tenant no PostgreSQL, fornecendo forte separação de dados entre tenants.

Como funciona

Quando uma requisição chega, o Matcher extrai o ID do tenant do token JWT (nunca de parâmetros de consulta ou headers que você controla). Em seguida, configura a conexão do banco de dados para usar o schema daquele tenant via SET LOCAL search_path, para que cada consulta seja executada em completo isolamento.

Mesmo se existisse um bug na camada de aplicação, o banco de dados impõe a separação. O isolamento de schema é aplicado por transação para prevenir poluição do pool de conexões.

Detalhes de implementação

ID do tenant apenas do JWT: Nunca aceito de parâmetros de requisição
Seleção automática de schema: Aplicada via auth.ApplyTenantSchema()
Isolamento por transação: Usa SET LOCAL search_path para delimitar cada transação do banco de dados
Sem acesso entre tenants: O banco de dados impõe o isolamento

Garantias de isolamento

Garantia	Implementação
Isolamento de dados	Schemas PostgreSQL separados
Escopo de consulta	`SET LOCAL search_path` por transação
Sem spoofing de tenant	Tenant apenas do JWT
Separação de auditoria	Tabelas de auditoria por tenant

Trilha de auditoria

O Matcher registra todas as ações em um log de auditoria imutável, somente-anexação, para conformidade e análise forense.

Eventos auditados

Categoria	Eventos
Acesso a Dados	Visualizar correspondências, visualizar exceções, exportar dados
Modificação de Dados	Criar correspondência, resolver exceção, atualizar regras
Configuração	Criar contexto, modificar fonte, alterar configurações

Consultar logs de auditoria

Use os endpoints de log de auditoria de governança para recuperar registros de auditoria:

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs" \
 -H "Authorization: Bearer $TOKEN"

Referência da API: Listar logs de auditoria

Mapeamentos de atores e privacidade

Os mapeamentos de atores associam identificadores do sistema (como os claims sub do JWT) com nomes legíveis e endereços de e-mail. Isso melhora a legibilidade dos logs de auditoria sem armazenar dados pessoais em cada entrada de log.

Gerenciar mapeamentos de atores

cURL

curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "display_name": "John Doe",
   "email": "john.doe@company.com"
 }'

Referência da API: Upsert de mapeamento de ator | Obter mapeamento de ator | Excluir mapeamento de ator

Para atender solicitações de direito ao apagamento, pseudonimize um ator para substituir seus dados pessoais por [REDACTED]. Esta ação é irreversível.

cURL

curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123/pseudonymize" \
 -H "Authorization: Bearer $TOKEN"

Referência da API: Pseudonimizar ator

Arquivos de logs de auditoria

Os logs de auditoria históricos são periodicamente comprimidos e movidos para armazenamento de longo prazo. Use os endpoints de arquivos para listar e baixar dados arquivados para revisões de conformidade.

cURL

curl -X GET "https://api.matcher.example.com/v1/governance/archives" \
 -H "Authorization: Bearer $TOKEN"

Referência da API: Listar arquivos | Baixar arquivo

Criptografia de dados

Criptografia em trânsito

O TLS criptografa todos os dados transmitidos para e do Matcher.

Requisito	Configuração
Protocolo	TLS 1.2 ou superior
Conjuntos de cifras	Apenas cifras fortes
Certificado	Certificado válido assinado por CA
HSTS	Habilitado com max-age de 1 ano

Criptografia em repouso

Tipo de Dado	Método de Criptografia
Banco de dados	PostgreSQL TDE (Transparent Data Encryption)
Armazenamento de arquivos	Criptografia AES-256
Backups	Criptografados antes do armazenamento
Segredos	Vault com criptografia envelope

Conformidade SOX

O Matcher mantém registros para requisitos de auditoria SOX (Sarbanes-Oxley).

Recursos de controle SOX

Controle	Recurso do Matcher
Segregação de funções	RBAC com permissões granulares
Gerenciamento de mudanças	Trilha de auditoria para todas as mudanças de configuração
Controle de acesso	Autenticação JWT com aplicação de funções
Trilha de auditoria	Logs imutáveis somente-anexação
Integridade de dados	Checksums e validação de transações

Segurança de API

Limitação de taxa

Alguns endpoints incluem limitação de taxa adicional para proteger contra abusos:

Tipo de Endpoint	Limitação de Taxa
Despacho de exceções	Sim
Endpoints de exportação	Sim
Processamento de callbacks	Sim

Proteção contra SSRF

O Matcher bloqueia requisições HTTP de saída para faixas de IP privadas ao despachar exceções para sistemas externos. Isso previne ataques de Server-Side Request Forgery (SSRF). As faixas bloqueadas incluem 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 e equivalentes IPv6.

Verificação de assinatura de webhooks

O Matcher assina payloads de webhooks de saída com HMAC-SHA256 usando um segredo compartilhado. A assinatura aparece no header X-Signature-256, permitindo que os receptores verifiquem a autenticidade.

Melhores práticas

Use acesso de menor privilégio

Conceda aos usuários apenas as permissões que eles precisam. Comece com acesso mínimo e adicione permissões conforme necessário.

Rotacione credenciais regularmente

Implemente rotação automática para credenciais de serviço e segredos JWT. Use tokens de curta duração sempre que possível.

Habilite o log de auditoria

Mantenha os logs de auditoria habilitados e revise-os regularmente. Configure alertas para atividades suspeitas.

Use limitação de taxa

Mantenha os limites de taxa padrão habilitados para proteger contra abusos. Ajuste os limites com base nos padrões de tráfego esperados.

Revise o acesso regularmente

Realize revisões de acesso periódicas. Remova o acesso prontamente quando usuários mudarem de função ou saírem.

Verifique assinaturas de webhooks

Sempre valide assinaturas HMAC-SHA256 em payloads de webhooks para confirmar que eles se originam do Matcher.

Monitore eventos de segurança

Configure monitoramento e alertas em tempo real para eventos de segurança. Investigue anomalias prontamente.

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

​Visão geral

​Proteção por camadas

​Autenticação

​Configuração

​Estrutura do token JWT

​Headers obrigatórios

​Validação de token

​Autorização (RBAC)

​Estrutura de permissão

​Lista completa de permissões

​Configuração

​Ingestão

​Correspondência

​Exceção

​Governança

​Relatórios

​Gerenciamento de funções

​Isolamento de tenant

​Como funciona

​Garantias de isolamento

​Trilha de auditoria

​Eventos auditados

​Consultar logs de auditoria

​Mapeamentos de atores e privacidade

​Gerenciar mapeamentos de atores

​Pseudonimização LGPD/GDPR

​Arquivos de logs de auditoria

​Criptografia de dados

​Criptografia em trânsito

​Criptografia em repouso

​Conformidade SOX

​Recursos de controle SOX

​Segurança de API

​Limitação de taxa

​Proteção contra SSRF

​Verificação de assinatura de webhooks

​Melhores práticas

​Próximos passos

Regras de correspondência

Roteamento de exceções

Visão geral

Proteção por camadas

Autenticação

Configuração

Estrutura do token JWT

Headers obrigatórios

Validação de token

Autorização (RBAC)

Estrutura de permissão

Lista completa de permissões

Configuração

Ingestão

Correspondência

Exceção

Governança

Relatórios

Gerenciamento de funções

Isolamento de tenant

Como funciona

Garantias de isolamento

Trilha de auditoria

Eventos auditados

Consultar logs de auditoria

Mapeamentos de atores e privacidade

Gerenciar mapeamentos de atores

Pseudonimização LGPD/GDPR

Arquivos de logs de auditoria

Criptografia de dados

Criptografia em trânsito

Criptografia em repouso

Conformidade SOX

Recursos de controle SOX

Segurança de API

Limitação de taxa

Proteção contra SSRF

Verificação de assinatura de webhooks

Melhores práticas

Próximos passos