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. Os dados de reconciliação financeira estão entre os mais sensíveis de qualquer organização — envolvem registros de transações, informações de contrapartes e obrigações regulatórias. Regulamentações como SOC 2, PCI DSS e requisitos das autoridades financeiras locais exigem controles específicos de acesso, criptografia e rastreabilidade. O Matcher foi projetado com esses requisitos em mente, oferecendo segurança em profundidade em cada camada da stack.

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	PostgreSQL com banco de dados por tenant (pool-por-tenant)
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 para o controle de acesso baseado em JWT. O Matcher delega toda a validação criptográfica de JWT a um provedor de autenticação externo e não guarda nenhum segredo JWT local próprio.

Configuração

Estas variáveis de ambiente controlam a autenticação:

Variável	Obrigatória	Descrição
`PLUGIN_AUTH_ENABLED`	Sim	Habilitar ou desabilitar a aplicação de autorização (`true`/`false`; padrão `false`)
`PLUGIN_AUTH_ADDRESS`	Quando auth habilitado	Endereço do serviço externo `plugin-auth`
`AUTH_PROVIDER`	Não	Provedor de validação: `plugin-auth`, `workos` ou `disabled`. Quando não definido, é derivado de `PLUGIN_AUTH_ENABLED`

AUTH_ENABLED e AUTH_SERVICE_ADDRESS são aceitos como aliases legados de PLUGIN_AUTH_ENABLED e PLUGIN_AUTH_ADDRESS. Definir um alias e sua forma atual com valores conflitantes é rejeitado na inicialização.

Quando PLUGIN_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

Com AUTH_PROVIDER=plugin-auth, a validação criptográfica é delegada ao serviço plugin-auth; com AUTH_PROVIDER=workos, o Matcher verifica localmente os JWTs de token de acesso do WorkOS contra o JWKS em cache. De qualquer forma, 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 tenant
`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/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN"

Validação de token

O Matcher valida tokens em cada requisição:

Verificação de assinatura: Delegada ao provedor de autenticação configurado (serviço plugin-auth ou JWKS do WorkOS) — o Matcher não guarda nenhum segredo de assinatura local
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 resolver o pool de banco de dados do tenant

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 de duas partes resource:action.

Estrutura de permissão

<resource>:<action>

Os recursos são substantivos de produto planos (no plural), sem prefixo de domínio nem segmento de sub-recurso. As ações são verbos que descrevem a operação realizada sobre o substantivo. Exemplos:

contexts:create — Criar contextos de reconciliação
match-runs:run — Executar ciclos de correspondência
exceptions:resolve — Resolver exceções

Lista completa de permissões

O Matcher define um conjunto plano de aproximadamente 35 recursos — não há agrupamento em domínios. Cada endpoint requer uma permissão resource:action específica verificada contra o serviço de autorização externo. As tabelas a seguir estão agrupadas apenas para facilitar a leitura; os slugs em si não carregam nenhum qualificador de domínio.

Configuração

Permissão	Descrição
`contexts:create`	Criar contextos de reconciliação
`contexts:read`	Visualizar contextos
`contexts:update`	Atualizar contextos
`contexts:delete`	Arquivar (exclusão lógica) contextos
`contexts:clone`	Clonar um contexto e sua configuração
`sources:create`	Criar fontes de dados
`sources:read`	Visualizar configuração de fonte
`sources:update`	Modificar configurações de fonte
`sources:delete`	Remover fontes de dados
`field-maps:create`	Criar mapeamentos de campo
`field-maps:read`	Visualizar mapeamentos de campo
`field-maps:update`	Atualizar mapeamentos de campo
`field-maps:delete`	Excluir mapeamentos de campo
`rules:create`	Criar regras de correspondência
`rules:read`	Visualizar regras de correspondência
`rules:update`	Atualizar regras de correspondência
`rules:delete`	Excluir regras de correspondência
`rules:reorder`	Reordenar a prioridade de avaliação das regras
`fee-schedules:create`	Criar agendamentos de tarifas
`fee-schedules:read`	Visualizar agendamentos de tarifas
`fee-schedules:update`	Atualizar agendamentos de tarifas
`fee-schedules:delete`	Excluir agendamentos de tarifas
`fee-schedules:simulate`	Simular cálculos de agendamentos de tarifas
`fee-rules:create`	Criar regras de tarifas
`fee-rules:read`	Visualizar regras de tarifas
`fee-rules:update`	Atualizar regras de tarifas
`fee-rules:delete`	Excluir regras de tarifas
`schedules:create`	Criar agendamentos
`schedules:read`	Visualizar agendamentos
`schedules:update`	Atualizar agendamentos
`schedules:delete`	Excluir agendamentos

Ingestão

Permissão	Descrição
`imports:create`	Fazer upload de arquivos de transação
`imports:preview`	Pré-visualizar a análise da importação antes de confirmar
`import-jobs:read`	Visualizar jobs de importação
`ingestion-transactions:search`	Pesquisar transações
`ingestion-transactions:ignore`	Marcar transações como ignoradas
`extraction-reviews:create`	Enfileirar extrações de documentos com IA e aprovar/rejeitar revisões
`extraction-reviews:read`	Visualizar revisões de extração

Correspondência

Permissão	Descrição
`match-runs:run`	Executar ciclos de correspondência
`match-runs:read`	Visualizar resultados dos ciclos de correspondência
`match-groups:read`	Visualizar grupos de correspondência
`match-groups:unmatch`	Desfazer correspondência de grupos
`open-items:read`	Visualizar o livro de itens em aberto residuais transportados
`manual-matches:create`	Criar correspondências manuais
`adjustments:create`	Criar lançamentos de ajuste
`rule-suggestions:create`	Produzir e aprovar/rejeitar sugestões de regras
`rule-suggestions:read`	Visualizar sugestões de regras

Exceções e disputas

Permissão	Descrição
`exceptions:read`	Visualizar exceções e histórico
`exceptions:resolve`	Forçar correspondência ou ajustar lançamentos
`exceptions:assign`	Atribuir exceções a usuários
`exceptions:dispatch`	Despachar exceções para sistemas externos
`callback-credentials:read`	Listar credenciais de callback
`callback-credentials:write`	Gerar ou rotacionar credenciais de callback
`callback-credentials:delete`	Revogar credenciais de callback
`disputes:read`	Visualizar disputas
`disputes:write`	Criar ou atualizar disputas
`disputes:close`	Encerrar disputas
`disputes:submit-evidence`	Enviar evidências de disputas
`comments:read`	Visualizar comentários
`comments:write`	Adicionar comentários em exceções
`comments:delete`	Excluir comentários

Os callbacks recebidos de sistemas externos são autenticados por um token bearer opaco, não por RBAC, portanto não existe uma permissão callbacks:process. As permissões callback-credentials:* protegem apenas a superfície protegida por JWT que gera, rotaciona, lista e revoga esses tokens.

Relatórios e análises

Permissão	Descrição
`dashboards:read`	Acessar análises e métricas do dashboard
`reports:read`	Visualizar relatórios (correspondidos, não correspondidos, resumo, variância)
`reports:export`	Exportar relatórios
`reports:count`	Contar linhas de relatórios
`export-jobs:create`	Criar jobs de exportação
`export-jobs:read`	Visualizar status de jobs de exportação
`export-jobs:cancel`	Cancelar jobs de exportação
`export-jobs:download`	Baixar arquivos de exportação

Governança e privacidade

Permissão	Descrição
`audit-logs:read`	Visualizar logs de auditoria
`archives:read`	Visualizar arquivos
`archives:download`	Baixar arquivos
`actor-mappings:read`	Visualizar mapeamentos de ator
`actor-mappings:write`	Criar ou atualizar mapeamentos de ator
`actor-mappings:delete`	Excluir mapeamentos de ator
`actor-mappings:pseudonymize`	Pseudonimizar atores (direito ao esquecimento do GDPR)
`actor-mappings:deanonymize`	Revelar identidades de atores pseudonimizadas

Discovery

Permissão	Descrição
`discovery-status:read`	Visualizar status do discovery
`discovery-connections:read`	Visualizar conexões de discovery
`discovery-connections:create`	Criar conexões de discovery
`discovery-connections:update`	Atualizar conexões de discovery
`discovery-connections:write`	Gravar dados de conexões de discovery
`discovery-connections:delete`	Excluir conexões de discovery
`discovery-connections:test`	Testar conexões de discovery
`discovery-connections:extract`	Disparar a extração do discovery
`discovery-extractions:read`	Visualizar extrações de discovery
`discovery-extractions:poll`	Consultar o status de extração do discovery
`discovery-refresh:execute`	Executar a atualização do discovery

System

Permissão	Descrição
`system-runtime-config:admin`	Administrar a configuração de runtime do sistema
`streaming-manifest:read`	Ler o manifesto de streaming

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 pool-por-tenant no PostgreSQL: os dados de cada tenant ficam no seu próprio banco de dados, 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, resolve o pool de conexões dedicado ao banco de dados daquele tenant, para que cada consulta seja executada contra o próprio banco de dados do tenant em completo isolamento. Não há troca de schema compartilhado — não se usa SET search_path.

Como os dados de cada tenant ficam em um banco de dados fisicamente separado, um bug na camada de aplicação ainda não consegue alcançar os dados de outro tenant.

Detalhes de implementação

ID do tenant apenas do JWT: Nunca aceito de parâmetros de requisição
Resolução automática de pool: O pool de conexões do banco de dados do tenant é resolvido a partir do contexto
Isolamento físico: As consultas de cada tenant são executadas contra o seu próprio banco de dados, não um compartilhado
Sem acesso entre tenants: Bancos de dados fisicamente separados impõem o isolamento

Garantias de isolamento

Garantia	Implementação
Isolamento de dados	Um banco de dados PostgreSQL separado por tenant
Escopo de consulta	Pool de conexões por tenant resolvido a partir do JWT
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

O parâmetro de rota do ID de ator aceita até 255 caracteres (correspondendo à restrição de coluna do banco de dados). Espaços em branco iniciais e finais são removidos automaticamente. Valores que excedam esse limite são rejeitados com um erro 400 Bad Request.

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

A operação de upsert retorna o mapeamento de ator persistido diretamente na resposta, para que você possa verificar os valores salvos sem uma requisição GET separada.

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]. A pseudonimização não é reversível a partir da aplicação; os registros subjacentes podem ser retidos conforme a política de conformidade e auditoria.

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 por destino. A assinatura aparece no header X-Signature-256, formatada como sha256=<hex-digest>, permitindo que os receptores verifiquem a autenticidade. (O despacho também define um header X-Idempotency-Key para entrega no máximo uma vez.)

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.

​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ções e disputas

​Relatórios e análises

​Governança e privacidade

​Discovery

​System

​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ções e disputas

Relatórios e análises

Governança e privacidade

Discovery

System

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