Clerk Integration

Secure Clerk authentication routes against VPNs, proxies, and Tor nodes via 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 tiempos de espera agotados.

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 || "", // Do not use NEXT_PUBLIC_ prefixes
});
 
export const config = {
  matcher: [
    // Exclude Next.js internals and all static files
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always execute for API and tRPC routes
    '/(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. Granular Route Policies

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 || "",
  
  // Define route-specific access policies
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Explicitly allow proxies on this route
  ],
  
  // Global fallback URL for unmatched blocked routes
  fallbackUrl: "/access-denied" 
});

2. Infrastructure Native Support

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", // Use 'cloudflare' for Cloudflare, or 'vercel' for Vercel/Nginx
});

3. Global Redis Caching (Optional)

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 }) // Cache globally for 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. Next.js Route Matcher (Critical)

Por defecto, Next.js ejecuta el middleware en cada solicitud HTTP. Si no se configura correctamente el comparador (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. Fail-Open vs. Fail-Closed Configurations

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

3. Edge Node Caching Limitations

La caché en memoria integrada retiene datos de clasificación IP por 5 minutos por nodo 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, pero no sincroniza el estado globalmente. Para minimizar el uso de la API y forzar una caché global real de 24 horas, se requiere una integración de 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 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.