Integración con Clerk

Protege las rutas de autenticación de Clerk contra VPNs, proxys y nodos Tor mediante Next.js Edge Middleware.

Características

• Configuración mínima requerida.
• Totalmente compatible con Vercel Edge, Cloudflare Workers y entornos Nginx propios.
• Bloquea el tráfico de alto riesgo en rutas sensibles (ej. /sign-up) mientras permite explícitamente el acceso a otras.
• La validación nativa de CIDR de Cloudflare previene intentos de elusión y suplantación de encabezados IP.
• Sistema de Caché de Dos Niveles: Caché en memoria integrada para mitigar picos de tráfico, con soporte nativo para integraciones globales con Redis.
• Respaldo Configurable: Aplica lógica de Fail-Open (priorizar disponibilidad) o Fail-Closed (priorizar máxima seguridad) durante timeouts.

Instalación

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

Guía de Implementación

Requisitos previos

Este paquete requiere Next.js Edge Middleware. Asegúrate de que exista un archivo middleware.ts (o .js) en la raíz de tu proyecto o dentro del directorio src/.

Uso Básico

Integra ProxyTracer con Clerk envolviendo clerkMiddleware(). Por defecto, esto aplica la comprobación de seguridad en todas las rutas coincidentes con la configuración del middleware de Next.js.

import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // No utilice prefijos NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // Excluir los componentes internos de Next.js y todos los archivos estáticos
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Ejecutar siempre para rutas de API y tRPC
    '/(api|trpc)(.*)',
  ],
};

Configuración Avanzada

Para entornos de producción, es recomendable implementar un control granular sobre las rutas protegidas y configurar los ajustes de proxy específicos del proveedor de infraestructura.

1. Políticas de ruta granulares

Aplica acciones específicas por ruta para equilibrar la seguridad y el acceso a los usuarios.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Definir políticas de acceso específicas por ruta
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Permitir explícitamente proxies en esta ruta
  ],
  
  // URL de reserva global para rutas bloqueadas sin coincidencia
  fallbackUrl: "/access-denied" 
});

2. Soporte nativo de infraestructura

Configura la extracción de IP basada en tu proveedor de infraestructura para validar de forma segura los rangos CIDR y prevenir la falsificación de encabezados.

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

3. Almacenamiento en caché global con Redis (Opcional)

ProxyTracer incluye una caché local en memoria de 5 minutos para entornos aislados de Edge. Para optimizar el uso de la API en una arquitectura global distribuida, proporciona un 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 }) // Caché global durante 24h
  }
});

Referencia de la API

Arquitectura y Seguridad

Para garantizar un rendimiento y rentabilidad óptimos al utilizar Next.js Edge Middleware, sigue estas pautas:

1. Coincidencia de rutas de Next.js (Crítico)

Por defecto, Next.js ejecuta el middleware en cada solicitud HTTP. Si no se configura correctamente el matcher, se realizarán llamadas innecesarias a la API para activos estáticos (ej. .png, .css, _next/static). Debes incluir el comparador de exclusión estándar de Next.js al fondo de tu archivo middleware.ts para omitir archivos estáticos, tal como se muestra en el ejemplo de Uso Básico.

2. Configuraciones Fail-Open vs. Fail-Closed

Por defecto, el paquete se configura con failOpen: true. Si la API de ProxyTracer excede el timeout o falla la conectividad de red, se permite que la solicitud continúe. Esto prioriza la alta disponibilidad y la experiencia del usuario. Para endpoints altamente sensibles (ej. transacciones financieras, verificación de identidad), se recomienda encarecidamente usar failOpen: false. Esto asegura que un fallo del sistema provoque un bloqueo estricto de seguridad.

3. Limitaciones del almacenamiento en caché en nodos Edge

La caché en memoria integrada retiene datos de clasificación de IPs por 5 minutos por nodo de Edge. Dado que plataformas como Vercel y Cloudflare distribuyen solicitudes en cientos de nodos globales, esta caché opera estrictamente a nivel local por nodo. Brinda protección eficaz para picos breves de tráfico, pero no sincroniza el estado globalmente. Para minimizar el uso de la API y forzar una caché global de 24 horas, se requiere una integración con una base de datos Redis.

Directrices de Seguridad

• Asegúrate de que la clave de la API de ProxyTracer no comience con NEXT_PUBLIC_. Si lo hace, el middleware arrojará un error y detendrá la aplicación al iniciar para protegerte de filtraciones accidentales al navegador.
• Si vas a desplegar (deploy) utilizando un proxy inverso como NGINX, necesitas configurar NGINX para pasar los encabezados X-Real-IP o X-Forwarded-For. Una vez configurado, ajusta trustedProxy: "vercel" en las opciones del middleware para que sepa cómo leerlos correctamente.

Licencia

Este software está bajo la Licencia Pública General Affero de GNU v3.0 (AGPLv3). Consulte el archivo LICENSE para obtener todos los detalles.