README

Horse Sanitize

O Horse Sanitize é um middleware de segurança de borda projetado para o ecossistema do framework Horse. Ele intercepta requisições HTTP e varre de forma recursiva parâmetros de consulta (Query), parâmetros de rota (Params) e o corpo da requisição (Body em formato JSON) para remover ou neutralizar conteúdos maliciosos comuns, como scripts de Cross-Site Scripting (XSS), injeções de HTML e tags de iframe indesejadas.

🛡️ Por que Utilizar?

• Defesa em Profundidade: Adiciona uma camada de segurança robusta logo na entrada do servidor, impedindo que strings infectadas atinjam seus controladores, lógica de negócio ou persistência em banco de dados.
• Prevenção de XSS Persistente (Stored XSS): Neutraliza scripts maliciosos de entrada (ex: <script>alert('hack')</script>), garantindo que dados salvos no banco não se tornem vetores de ataque ao serem renderizados futuramente no navegador de outros usuários.
• Automação Global: Dispensa a necessidade de escrever rotinas manuais e repetitivas de limpeza de strings em cada rota ou propriedade de classe (como DTOs).
• Mitigação de Vulnerabilidades OWASP: Ajuda a blindar a aplicação contra entradas inesperadas e malformadas de dados textuais.

📈 Situações e Cenários de Uso Recomendados

1. APIs Públicas e Formulários de Cadastro: Perfeito para endpoints expostos na internet que recebem inputs livres, tais como: formulários de contato, cadastros de clientes, comentários de blogs, avaliações e descrições textuais.
2. Backends para Single Page Applications (SPA): Indispensável para servidores Horse que alimentam interfaces em React, Vue ou Angular que renderizam dinamicamente conteúdos textuais inseridos por usuários.
3. Aplicações sem Suporte a Rich Text (HTML): Ideal quando o sistema espera apenas dados puramente textuais e qualquer marcação HTML inserida deve ser considerada perigosa ou supérflua.
4. Proteção de Sistemas Legados: Útil para introduzir uma barreira de segurança rápida de borda em servidores que expõem APIs de sistemas antigos que carecem de sanitização interna detalhada.

⚙️ Instalação

A instalação verificada é feita pelo Boss4D:

boss4d package install horse-sanitize@1.0.0

⚡ Como Usar

⚠️ IMPORTANTE: Ordem de Registro do Middleware

Para que o Horse Sanitize consiga higienizar o corpo da requisição (Body), ele deve ser registrado no pipeline do Horse após o middleware de parser de JSON (como o horse-jhonson ou semelhante).

Caso seja registrado antes, a string bruta do corpo não poderá ser sanitizada, pois o Horse expõe a string bruta do body como somente leitura (read-only). O horse-sanitize manipula diretamente a árvore de objetos do JSON em memória (TJSONObject) gerada pelo parser.

1. Configuração Básica (Higienização Completa)

Nesta configuração, o middleware higieniza automaticamente: Query, Params e o Body (JSON) utilizando o sanitizador padrão nativo.

uses
  Horse,
  Horse.Jhonson,
  Horse.Sanitize;

begin
  // 1. Converte a string do Body para TJSONObject
  THorse.Use(Jhonson);
  
  // 2. Sanitiza os dados do TJSONObject, Query e Params
  THorse.Use(Sanitize);

  THorse.Post('/contato',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      // O Req.Body já chega aqui 100% livre de tags maliciosas
      Res.Send(Req.Body<TJSONObject>);
    end);

  THorse.Listen(9000);
end.

2. Configurações Avançadas

Você pode personalizar o comportamento do middleware passando um registro TSanitizeConfig.

A. Limitar a Higienização a Componentes Específicos

Por exemplo, você pode desejar sanitizar apenas os parâmetros de consulta (Query) e de rota (Params), deixando o corpo intocado:

var
  LConfig: TSanitizeConfig;
begin
  LConfig.Options := [soQuery, soParams]; // Ignora soBody
  LConfig.CustomSanitizer := nil;         // Usa o padrão
  
  THorse.Use(Sanitize(LConfig));
end.

B. Utilizar um Sanitizador Customizado

Você pode fornecer sua própria função de limpeza para regras de negócio específicas (como escape de caracteres adicionais ou expressões regulares personalizadas):

// Função customizada compatível com Delphi e Lazarus
function MeuSanitizerCustomizado(const AValue: string): string;
begin
  Result := AValue;
  // Exemplo simples: remove o caractere de aspas simples para mitigar quebras de string
  Result := StringReplace(Result, '''', '', [rfReplaceAll]);
end;

var
  LConfig: TSanitizeConfig;
begin
  LConfig := TSanitizeConfig.Default;
  LConfig.CustomSanitizer := MeuSanitizerCustomizado;
  
  THorse.Use(Sanitize(LConfig));
end.

🛠️ Comportamento do Sanitizador Padrão

Por padrão, o sanitizador realiza as seguintes ações de forma insensível a maiúsculas/minúsculas:

1. Remoção de Tags de Script: Remove blocos inteiros <script ...> ... </script> e seus conteúdos.
2. Remoção de Iframes: Remove blocos <iframe ...> ... </iframe>.
3. Remoção de Protocolos Javascript: Remove chamadas javascript: em links ou âncoras.
4. Desativação de Eventos Inline: Altera atributos de eventos comuns (como onerror, onload, onclick, onmouseover) para versões inofensivas (ex: x-onerror, x-onload), fazendo com que o navegador não os execute como código ativo.

💻 Compatibilidade

• Delphi XE7 ou superior.
• Lazarus / Free Pascal (FPC 3.2+).
• Compatível com todos os providers de transporte do Horse (Indy, CrossSocket, mORMot2, etc.).
• Desenvolvido sob princípios Clean Code, SOLID e thread-safe.

📄 Licença

Este projeto está licenciado sob a Apache License 2.0.