Integração com Clerk

Proteja rotas de autenticação do Clerk contra VPNs, proxies e nós Tor via Next.js Edge Middleware.

Recursos

• Configuração mínima necessária.
• Totalmente compatível com Vercel Edge, Cloudflare Workers e ambientes auto-hospedados com Nginx.
• Bloqueie tráfego de alto risco em rotas sensíveis (ex.: /sign-up) enquanto permite explicitamente o acesso a outras.
• A validação nativa de CIDR da Cloudflare impede a falsificação de cabeçalhos de IP e tentativas de bypass.
• Sistema de Cache em Duas Camadas: Cache em memória integrado para mitigação de picos de tráfego, com suporte nativo para integrações globais com Redis.
• Fallback Configurável: Aplique lógica de Fail-Open (priorizar disponibilidade) ou Fail-Closed (priorizar segurança estrita) durante timeouts da API.

Instalação

npm install proxytracer-clerk-middleware
# or
yarn add proxytracer-clerk-middleware
pnpm add proxytracer-clerk-middleware

Guia de Implementação

Pré-requisitos

Este pacote requer o Next.js Edge Middleware. Certifique-se de que um arquivo middleware.ts (ou .js) exista na raiz do seu projeto ou dentro do seu diretório src/.

Uso Básico

Integre o ProxyTracer com o Clerk envolvendo o clerkMiddleware(). Por padrão, isso aplica a verificação de segurança em todas as rotas correspondentes à configuração de middleware do Next.js.

import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // Não utilize prefixos NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // Exclua elementos internos do Next.js e todos os arquivos estáticos
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Execute sempre para rotas de API e tRPC
    '/(api|trpc)(.*)',
  ],
};

Configuração Avançada

Para ambientes de produção, é recomendado implementar controle granular sobre rotas protegidas e definir configurações específicas de proxy da infraestrutura.

1. Políticas de Rota Granulares

Aplique ações específicas por rota para equilibrar segurança e acesso do usuário.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Defina políticas de acesso específicas por rota
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Permitir proxies explicitamente nesta rota
  ],
  
  // URL de fallback global para rotas bloqueadas sem correspondência
  fallbackUrl: "/access-denied" 
});

2. Suporte Nativo de Infraestrutura

Configure a extração de IP com base no seu provedor de infraestrutura para validar com segurança faixas CIDR e evitar falsificação de cabeçalhos.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Use 'cloudflare' para Cloudflare ou 'vercel' para Vercel/Nginx
});

3. Cache Redis Global (Opcional)

O ProxyTracer inclui um cache em memória local de 5 minutos para isolados de Edge. Para otimizar a utilização da API em uma arquitetura global distribuída, forneça um adaptador Redis personalizado.

import { Redis } from '@upstash/redis';
 
const redis = Redis.fromEnv();
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  cache: {
    get: async (key) => await redis.get(key),
    set: async (key, isProxy) => await redis.set(key, isProxy, { ex: 86400 }) // Armazenar em cache globalmente por 24h
  }
});

Referência da API

Considerações de Arquitetura e Segurança

Para garantir o desempenho ideal e a eficiência de custos ao utilizar o Next.js Edge Middleware, observe as seguintes diretrizes:

1. Matcher de Rotas do Next.js (Crítico)

Por padrão, o Next.js executa o middleware em cada requisição HTTP. Não configurar adequadamente o matcher resultará em invocações desnecessárias da API para arquivos estáticos (ex.: .png, .css, _next/static). Você deve incluir o matcher de exclusão padrão do Next.js no final do seu arquivo middleware.ts para ignorar arquivos estáticos, como demonstrado no exemplo de Uso Básico.

2. Configurações Fail-Open vs. Fail-Closed

Por padrão, o pacote está configurado com failOpen: true. Se a API do ProxyTracer expirar por timeout ou ocorrer falha de conectividade na rede, a requisição é autorizada a prosseguir. Isso prioriza a alta disponibilidade e a experiência do usuário. Para endpoints altamente sensíveis (ex.: transações financeiras, verificação de identidade), é altamente recomendável definir failOpen: false. Isso garante que uma falha no sistema resulte em um bloqueio de segurança rigoroso.

3. Limitações do Cache em Nós Edge

O cache em memória integrado retém os dados de classificação de IP por 5 minutos por isolado Edge. Como plataformas como a Vercel e a Cloudflare distribuem requisições entre centenas de nós isolados globalmente, este cache opera estritamente de forma local por nó. Ele fornece proteção eficaz contra picos de tráfego, mas não sincroniza o estado globalmente. Para minimizar o uso da API e aplicar um cache global verdadeiro de 24 horas, é necessária a integração com um banco de dados Redis.

Diretrizes de Segurança

• Certifique-se de que sua chave de API do ProxyTracer não comece com NEXT_PUBLIC_. Se começar, o middleware lançará um erro e interromperá a execução na inicialização para evitar que ela seja vazada acidentalmente para o navegador.
• Se você estiver implantando, por exemplo, com um proxy reverso Nginx, configure o Nginx para encaminhar os cabeçalhos X-Real-IP ou X-Forwarded-For. Depois disso, basta definir trustedProxy: "vercel" nas opções do middleware para que ele saiba como lê-los corretamente.

Licença

Este software é licenciado sob a GNU Affero General Public License v3.0 (AGPLv3). Consulte o arquivo LICENSE para obter todos os detalhes.