> ## 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
> Configure a autenticação, o isolamento de tenants, a postura de transporte, a trilha de auditoria e os controles de integração de saída do Matcher.
O comportamento de segurança do Matcher é definido no deploy. Esta página descreve os controles implementados pelo Matcher e as fronteiras que continuam sob responsabilidade das suas plataformas de identidade, rede e armazenamento. Ela não é uma certificação de conformidade.
## Autenticação e autorização
***
O Matcher usa `AUTH_PROVIDER` para escolher o comportamento de autenticação:
| Provedor | Comportamento |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-auth` | O Matcher delega a confiança no token e as decisões de permissão ao serviço `plugin-auth` configurado, por meio da `lib-auth`. O Matcher não guarda nenhum segredo local de assinatura de JWT. |
| `disabled` | O Matcher não aplica autenticação por bearer token nem autorização. |
Quando `AUTH_PROVIDER` não está definida, o Matcher a deriva de `PLUGIN_AUTH_ENABLED`. Habilitada, ela escolhe `plugin-auth`. Desabilitada, ela escolhe `disabled`. O provedor `plugin-auth` precisa de `PLUGIN_AUTH_ADDRESS`. O Matcher rejeita qualquer outro valor de provedor, incluindo o provedor `workos`, já aposentado. As variáveis antigas `AUTH_ENABLED` e `AUTH_SERVICE_ADDRESS` continuam sendo apelidos das variáveis `PLUGIN_AUTH_*` atuais. Apelidos em conflito impedem a inicialização.
Quando você habilita a autenticação, as operações de API protegidas exigem um bearer token:
```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts" \
-H "Authorization: Bearer $TOKEN"
```
Não mantenha um inventário estático de permissões nos runbooks de deploy. A política da rota e do provedor define as exigências de permissão, e ela pode evoluir junto com o produto. Use a referência da API e a configuração do provedor de autorização ao atribuir papéis.
## Isolamento de tenants
***
Em configurações com autenticação desabilitada e de tenant único, o Matcher usa `DEFAULT_TENANT_ID` e `DEFAULT_TENANT_SLUG`. No modo multi-tenant (`MULTI_TENANT_ENABLED=true`), o provedor resolvido deve ser `plugin-auth`, e a requisição autenticada deve trazer uma claim `tenant_id` ou `tenantId` válida. O Matcher rejeita a inicialização quando o provedor resolvido é `disabled`. O Matcher não aceita um seletor de tenant controlado pelo chamador vindo de query string ou de corpo de requisição.
O Tenant Manager resolve um pool dedicado do PostgreSQL para cada tenant. O tenant padrão usa o pool raiz. O Matcher não usa o `SET search_path` do PostgreSQL para trocar o schema do tenant. Trate as credenciais de banco, as fronteiras de rede e a configuração do Tenant Manager como parte da fronteira de isolamento e verifique-as no seu deploy.
## Transporte e conexões de infraestrutura
***
O Matcher pode terminar TLS com `SERVER_TLS_CERT_FILE` e `SERVER_TLS_KEY_FILE`, ou operar atrás de um proxy confiável que termina o TLS, com `TLS_TERMINATED_UPSTREAM=true`. Configure o certificado e a chave juntos.
A exigência de TLS nas dependências precisa ser ativada. Defina a flag aplicável para que a inicialização falhe quando a configuração de conexão dela não declarar TLS:
* `POSTGRES_TLS_REQUIRED`
* `POSTGRES_REPLICA_TLS_REQUIRED`
* `REDIS_TLS_REQUIRED`
* `RABBITMQ_TLS_REQUIRED`
* `OBJECT_STORAGE_TLS_REQUIRED`
Essas flags protegem as conexões de dependência configuradas. Elas não substituem os controles de ingress, rede, certificado ou segurança de armazenamento fornecidos pelo deploy.
## Trilha de auditoria e mapeamentos de atores
***
O Matcher grava registros de auditoria para os workflows de mutação instrumentados. Os registros de auditoria são somente-anexação e ficam ligados por uma cadeia de hash por tenant que evidencia adulteração. O endpoint de verificação continua somente leitura e informa o resultado dos registros que inspecionou.
```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify" \
-H "Authorization: Bearer $TOKEN"
```
Os mapeamentos de atores podem associar um ID de ator opaco a um nome de exibição e a um e-mail. Fora dos ambientes local, de desenvolvimento e de teste, defina `ACTOR_PII_ENCRYPTION_KEY` com uma chave de 32 bytes codificada em base64 antes de usá-los. Quando ela não está definida, as operações de mapeamento de ator retornam um erro de criptografador obrigatório, e o Matcher nunca guarda em texto puro os dados pessoais dos mapeamentos de atores. O Matcher trata os registros de auditoria à parte, e eles podem reter o `actorId` bruto, que pode ser um endereço de e-mail. Com uma chave, o Matcher criptografa os dados pessoais armazenados dos mapeamentos de atores e oferece suporte às operações de pseudonimização e exclusão. Determine à parte as obrigações de retenção, privacidade e legais do seu deploy.
## Integrações de saída
***
Os conectores de despacho de exceções usam controles de SSRF que rejeitam destinos privados, de loopback e link-local por padrão. Revise qualquer configuração que permita destinos privados antes de usá-la em produção.
Os fluxos de webhook e de callback têm seus próprios mecanismos de verificação e idempotência. Configure segredos compartilhados ou faixas de IP de origem confiáveis apenas nas configurações do conector correspondente. Não trate esta página como um contrato de protocolo. Use a referência da API para os headers e o contrato de payload de uma integração específica.
## Checklist operacional
***
* Escolha e teste o provedor de autenticação pretendido antes de expor o Matcher.
* Habilite a autenticação antes de habilitar o modo multi-tenant.
* Exija TLS em cada dependência que não deve aceitar conexões em texto puro.
* Mantenha os papéis de autorização com o menor privilégio e revise-os no provedor de identidade.
* Monitore os registros de auditoria e investigue de forma independente uma verificação de cadeia que falhe.
* Mantenha armazenamento, backups, certificados e segredos protegidos pelos controles do deploy.
## Próximos passos
***
Veja quais valores de runtime podem mudar sem reiniciar o Matcher.
Gerencie mapeamentos de atores, logs de auditoria e arquivos.