> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Segurança > Conheça a segurança em camadas do Matcher: autenticação, RBAC, isolamento entre tenants, criptografia e log de auditoria em todos os níveis. 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: ```json theme={null} { "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: ```bash theme={null} 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: 1. **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 2. **Verificação de expiração**: Rejeita tokens expirados (claim `exp`) 3. **Verificação de not-before**: Rejeita tokens usados antes do tempo `nbf` 4. **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 ``` : ``` 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** 1. **ID do tenant apenas do JWT**: Nunca aceito de parâmetros de requisição 2. **Resolução automática de pool**: O pool de conexões do banco de dados do tenant é resolvido a partir do contexto 3. **Isolamento físico**: As consultas de cada tenant são executadas contra o seu próprio banco de dados, não um compartilhado 4. **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: ```bash theme={null} curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs" \ -H "Authorization: Bearer $TOKEN" ``` Referência da API: [Listar logs de auditoria](/pt/reference/matcher/list-audit-logs) ## 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`. ```bash cURL theme={null} 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](/pt/reference/matcher/upsert-actor-mapping) | [Obter mapeamento de ator](/pt/reference/matcher/get-actor-mapping) | [Excluir mapeamento de ator](/pt/reference/matcher/delete-actor-mapping) ### Pseudonimização LGPD/GDPR 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. ```bash cURL theme={null} 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](/pt/reference/matcher/pseudonymize-actor) ### 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. ```bash cURL theme={null} curl -X GET "https://api.matcher.example.com/v1/governance/archives" \ -H "Authorization: Bearer $TOKEN" ``` Referência da API: [Listar arquivos](/pt/reference/matcher/list-archives) | [Baixar arquivo](/pt/reference/matcher/download-archive) ## 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=`, 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 *** Conceda aos usuários apenas as permissões que eles precisam. Comece com acesso mínimo e adicione permissões conforme necessário. Implemente rotação automática para credenciais de serviço e segredos JWT. Use tokens de curta duração sempre que possível. Mantenha os logs de auditoria habilitados e revise-os regularmente. Configure alertas para atividades suspeitas. Mantenha os limites de taxa padrão habilitados para proteger contra abusos. Ajuste os limites com base nos padrões de tráfego esperados. Realize revisões de acesso periódicas. Remova o acesso prontamente quando usuários mudarem de função ou saírem. Sempre valide assinaturas HMAC-SHA256 em payloads de webhooks para confirmar que eles se originam do Matcher. Configure monitoramento e alertas em tempo real para eventos de segurança. Investigue anomalias prontamente. ## Próximos passos *** Configure regras de correspondência com segurança. Configure fluxos de trabalho de exceções seguros.