Clerk Integration

Secure Clerk authentication routes against VPNs, proxies, and Tor nodes via Next.js Edge Middleware.

Fonctionnalités

• Configuration minimale requise.
• Entièrement compatible avec Vercel Edge, Cloudflare Workers et les architectures NGINX hébergées en externe.
• Bloquez le trafic à haut risque sur des points d'entrée critiques (ex. /sign-up) tout en laissant un accès totalement fluide sur les autres sections.
• Validation CIDR native intégrée aux réseaux Cloudflare pour neutraliser toute tentative de contournement ou d'usurpation d'en-tête.
• Système de Cache à Deux Niveaux : Cache en mémoire intégré pour amortir les pics de requêtes intenses, assorti d'une prise en charge native pour des bases externes Redis mondiales.
• Résilience Paramétrable : Choisissez d'activer une stratégie Fail-Open (priorité absolue à l'accessibilité) ou Fail-Closed (protection étanche prioritaire) en cas de dépassement exceptionnel du délai d'attente.

Installation

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

Guide d'implémentation

Prérequis

Ce package nécessite l'emploi d'un middleware Next.js Edge. Vérifiez bien qu'un fichier middleware.ts (ou .js) réside à la racine de votre projet ou à l'intérieur de votre répertoire src/.

Utilisation de base

Intégrez ProxyTracer avec Clerk de manière directe en enveloppant clerkMiddleware(). De base, cela déploie la vérification sécuritaire sur toutes les routes éligibles au filtre de votre middleware 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)(.*)',
  ],
};

Configuration avancée

Dans les environnements de production, il est vivement conseillé d'implémenter un contrôle fin ciblé sur vos routes à protéger et d'adapter rigoureusement les réglages selon votre hébergeur web.

1. Granular Route Policies

Définit des politiques par route, vous assurant l'équilibre parfait entre haute sécurité et confort de navigation.

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

Ajustez la méthode d'extraction de l'IP selon les normes techniques de votre hébergeur pour valider de façon étanche les plages CIDR et éliminer tout risque d'usurpation.

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 est doté d'un cache local en mémoire cadencé sur 5 minutes, spécialisé pour l'exécution isolée à l'Edge. Afin d'optimiser radicalement l'empreinte de l'API sur des infrastructures distribuées à l'international, adjoindre un connecteur Redis personnalisé est vivement suggéré.

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
  }
});

Référence de l'API

Architecture & Sécurité

Pour garantir des performances de pointe et préserver l'économie financière de votre middleware Next.js Edge, veillez à suivre scrupuleusement les règles suivantes :

1. Next.js Route Matcher (Critical)

Par défaut, Next.js sollicite son middleware à chaque requête HTTP d'entrée. Une erreur d'adressage dans le matcher provoquerait l'envoi d'appels API superflus lors du chargement d'éléments statiques (.png, .css, _next/static). Vous devez impérativement joindre le matcher d'exclusion universel Next.js en bas de votre fichier middleware.ts pour éluder l'analyse des ressources statiques, comme illustré dans l'exemple de Base.

2. Fail-Open vs. Fail-Closed Configurations

Initialement, ce module est réglé avec l'attribut failOpen: true. Dans l'éventualité où l'API de ProxyTracer dépasserait son temps limite d'exécution ou qu'une panne de réseau subviendrait, la requête sera laissée passante. Ceci favorise sans condition la continuité du service pour vos visiteurs. Pour vos flux financiers ultra-critiques ou des étapes de validation d'identité formelles, basculer vers failOpen: false est impératif afin de muer tout incident en un verrouillage hermétique.

3. Edge Node Caching Limitations

Le cache en mémoire intégré conserve vos diagnostics d'adressage IP durant 5 minutes au niveau de chaque nœud Edge opérationnel. Sachant que les réseaux Cloudflare et Vercel éparpillent les requêtes entrantes parmi des centaines de serveurs indépendants à travers le globe, ce cache local intervient isolément sur son propre nœud de calcul. Si cela pare efficacement vos montées en charge soudaines, cela n'homogéneise pas le statut globalement. Afin de comprimer votre utilisation de l'API et de pérenniser un véritable cache unifié sur 24 heures partout dans le monde, l'adjonction d'une base Redis centralisée est obligatoire.

Directives de sécurité

• Prenez garde de ne jamais préfixer votre clé API ProxyTracer avec la syntaxe NEXT_PUBLIC_. Une telle négligence provoquera une erreur d'arrêt du middleware dès le démarrage initial pour interdire que ce secret ne fuite involontairement vers le navigateur.
• Si vos applications cohabitent derrière un serveur mandataire inverse tel que NGINX, vous aurez à configurer l'acheminement effectif des en-têtes X-Real-IP ou X-Forwarded-For. Cette formalité complétée, optez simplement pour trustedProxy: "vercel" au cœur des options de votre middleware, afin que celui-ci apprenne à lier et décrypter correctement la source.

Licence

Ce logiciel est sous licence GNU Affero General Public License v3.0 (AGPLv3). Consultez le fichier LICENSE pour plus de détails.