@credithub/proxy NPM

Credithub Proxy

Este projeto é um proxy que intercepta conexões HTTP e HTTPS. Ele faz isso de forma simples, criando um "homem no meio" (MITM) para descriptografar e analisar o tráfego HTTPS. Em seguida, o proxy encaminha as requisições através de um WebSocket para um cliente que realiza as requisições reais na internet e depois retorna a resposta para o usuário.

Como Funciona

Cliente → Proxy (CONNECT):
O cliente (por exemplo, o navegador ou o curl) envia uma requisição CONNECT para o proxy para estabelecer um túnel seguro para o site desejado.
Proxy Responde com "200 Connection Established":
O proxy responde com um status 200, indicando que o túnel foi estabelecido.
Proxy Intercepta a Conexão HTTPS (MITM):
O proxy gera dinamicamente um certificado para o site requisitado. Isso permite que ele “finja” ser o site para o cliente.
Atenção: O cliente precisará confiar na sua CA (Autoridade Certificadora) personalizada para evitar avisos de segurança.
Handshake TLS e Comunicação Descriptografada:
O cliente inicia o handshake TLS com o proxy. Assim que a conexão segura é estabelecida, o proxy pode ler a requisição HTTPS.
Encaminhamento via WebSocket:
A requisição interceptada é enviada via WebSocket para um cliente interno que executa o fetch para o site real.
Resposta:
Quando o cliente WebSocket recebe a resposta, o proxy a reencapsula na conexão TLS e a envia de volta para o cliente original.

Fluxo de Autenticação WebSocket

O sistema implementa um mecanismo de autenticação seguro entre o servidor proxy e os clientes WebSocket:

Conexão Inicial:
- O servidor WebSocket opera na porta 3001
- O cliente WebSocket se conecta a este endpoint usando o URL ws://localhost:3001/
- Requisições HTTP regulares (não WebSocket) receberão a mensagem MAGIC_MESSAGE definida no servidor
Processo de Autenticação:
- Após a conexão, o cliente envia mensagens de keepalive com seu nickname
- O servidor inicia o processo de validação enviando uma requisição ao MAGIC_HOST
- O cliente processa esta requisição e retorna a resposta
- Se a resposta contiver exatamente o MAGIC_MESSAGE esperado, o cliente é considerado autenticado
Validação Periódica:
- Clientes autenticados são revalidados a cada intervalo de tempo (padrão: 5 minutos)
- Isso garante que apenas clientes confiáveis continuem processando requisições
- Timeouts de validação são gerenciados para evitar vazamentos de memória
Manipulação de Erros e Reconexão:
- O cliente implementa um mecanismo de reconexão com backoff em caso de desconexão
- Timeouts são gerenciados adequadamente para evitar vazamentos de memória
- Logs detalhados são gerados para facilitar a depuração

Gerando os Certificados

Para que o proxy possa gerar os certificados necessários para interceptar as conexões HTTPS, você precisa criar uma Autoridade Certificadora (CA) personalizada. Use os comandos abaixo no terminal:

openssl genrsa -out mitm-ca.key 2048
openssl req -new -x509 -days 365 -key mitm-ca.key -out mitm-ca.crt -subj "/CN=Credithub Proxy CA"

Esses comandos irão gerar:

mitm-ca.key: A chave privada da CA.
mitm-ca.crt: O certificado da CA, que será usado para assinar os certificados gerados dinamicamente para cada conexão interceptada.

Como Usar

Instale as Dependências:
Certifique-se de ter o Node.js instalado. Em seguida, instale as dependências do projeto:
```
npm install
```
Inicie o Servidor Proxy:
Inicie o proxy (exemplo usando tsx):
```
npx tsx src/server.ts
```
Inicie o Cliente WebSocket:
Em outra janela de terminal, inicie o cliente que se conecta via WebSocket:
```
npx tsx src/client.ts
```
Configure seu Cliente HTTP:
Configure seu navegador ou ferramenta de linha de comando (como o curl) para usar o proxy. Por exemplo, com o curl:
```
curl https://ipinfo.io --proxy localhost:8080 -v -k
```
Nota: O parâmetro -k desabilita a verificação do certificado. Em um ambiente real, é melhor adicionar o certificado da CA aos certificados confiáveis do sistema.

Listar Nós de Saída

Este endpoint permite visualizar os nós de saída ativos do proxy. Ao chamar a URL /list-clients, o sistema retorna uma resposta em JSON contendo:

clients: Uma lista de todos os nós conectados, com seus respectivos IPs.
authenticatedClients: Uma lista dos nós autenticados, onde cada um possui um identificador único (nickname) e o IP correspondente.

Exemplo de uso:

% curl localhost:4000/list-clients

{
  "clients": [
    {
      "ip": "::1"
    }
  ],
  "authenticatedClients": [
    {
      "nickname": "0194ebce-737d-72ad-8f40-d2b1793b1055",
      "ip": "::1"
    }
  ]
}

Esse recurso é útil para monitorar os nós disponíveis e identificar quais clientes estão autenticados e prontos para processar as requisições.

Usar um Nó de Saída Específico

Para direcionar uma requisição por um nó de saída específico, inclua o cabeçalho x-exitnode na sua chamada HTTP, informando o identificador único (nickname) do nó desejado.

Por exemplo, o comando abaixo faz uma requisição para https://ipinfo.io utilizando o proxy que está rodando na porta 8080 e força a utilização do nó de saída com o nickname 0194ebce-737d-72ad-8f40-d2b1793b105:

% curl "https://ipinfo.io" --proxy 'localhost:8080' -k -v --header "x-exitnode: 0194ebce-737d-72ad-8f40-d2b1793b105"

Explicação:

--proxy 'localhost:8080': Define o proxy local que intercepta a requisição.
-k: Permite conexões com certificados SSL não verificados (útil para testes com a CA personalizada).
--header "x-exitnode: ...": Especifica o nó de saída a ser utilizado, garantindo que a requisição seja encaminhada pelo cliente correspondente.

Assim, você pode controlar qual nó de saída será utilizado para cada requisição, facilitando o gerenciamento e a distribuição das conexões através do seu proxy.

Resumo Simples

Proxy: Intercepta requisições HTTP/HTTPS e cria um túnel seguro.
MITM: Gera certificados "na hora" para ler as conexisições HTTPS.
WebSocket: Encaminha as requisições interceptadas para um cliente que faz o acesso real à internet.
Certificados: Gere sua CA com os comandos fornecidos e faça o proxy assinar os certificados dos sites.