Intégration Clerk

Sécurisez les routes d'authentification Clerk contre les VPN, les proxys et les nœuds Tor 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 || "", // N'utilisez pas de préfixes NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // Exclure les éléments internes de Next.js et tous les fichiers statiques
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Toujours exécuter pour les routes API et tRPC
    '/(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. Règles de routage granulaires

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 || "",
  
  // Définir des règles d'accès spécifiques aux routes
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Autoriser explicitement les proxys sur cette route
  ],
  
  // URL de repli globale pour les routes bloquées sans correspondance
  fallbackUrl: "/access-denied" 
});

2. Prise en charge native de l'infrastructure

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", // Utilisez 'cloudflare' pour Cloudflare, ou 'vercel' pour Vercel/Nginx
});

3. Mise en cache Redis globale (Optionnel)

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 }) // Mettre en cache globalement pendant 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. Matcher de routes Next.js (Critique)

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. Configurations Fail-Open vs Fail-Closed

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. Limitations de la mise en cache sur les nœuds Edge

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.