Clerk Integration

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

Funktionen

• Minimale Konfiguration erforderlich.
• Vollständig kompatibel mit Vercel Edge, Cloudflare Workers und selbst gehosteten NGINX-Umgebungen.
• Blockieren Sie hochriskanten Datenverkehr auf sensiblen Routen (z. B. /sign-up), während der Zugriff auf andere ausdrücklich erlaubt bleibt.
• Native Cloudflare-CIDR-Validierung verhindert Versuche der IP-Header-Fälschung und Umgehung.
• Zweistufiges Caching-System: Integrierter Speicher-Cache zur Abfertigung von Lastspitzen, mit nativer Unterstützung für weltweite Redis-Integrationen.
• Konfigurierbares Fallback: Setzen Sie im Falle von API-Timeouts w Wahlweise auf Fail-Open (Priorität auf Verfügbarkeit) oder Fail-Closed (Priorität auf strikte Sicherheit).

Installation

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

Implementierungsleitfaden

Voraussetzungen

Dieses Paket erfordert Next.js Edge Middleware. Stellen Sie sicher, dass eine Datei middleware.ts (oder .js) im Stammverzeichnis Ihres Projekts oder im Ordner src/ existiert.

Grundlegende Nutzung

Integrieren Sie ProxyTracer mit Clerk, indem Sie clerkMiddleware() umschließen. Standardmäßig wendet dies die Sicherheitsprüfung auf alle Routen an, die der Konfiguration der Next.js-Middleware entsprechen.

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)(.*)',
  ],
};

Erweiterte Konfiguration

Für Produktionsumgebungen wird empfohlen, eine feinkörnige Kontrolle über die geschützten Routen zu implementieren und spezifische Infrastruktur-Proxy-Einstellungen zu konfigurieren.

1. Granular Route Policies

Wenden Sie routenspezifische Aktionen an, um die Balance zwischen Sicherheit und Nutzerfreundlichkeit optimal zu halten.

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

Konfigurieren Sie die IP-Extraktion entsprechend Ihrem Infrastruktur-Anbieter, um CIDR-Bereiche sicher zu verifizieren und Header-Falsifikation zu verhindern.

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 verfügt über einen 5-minütigen lokalen Speicher-Cache für Edge-Isolates. Um die API-Nutzung in einer verteilten globalen Architektur weiter zu optimieren, stellen Sie einen benutzerdefinierten Redis-Adapter bereit.

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

API-Referenz

Architektur & Sicherheit

Um optimale Leistung und Kosteneffizienz bei der Nutzung der Next.js Edge Middleware sicherzustellen, beachten Sie bitte folgende Richtlinien:

1. Next.js Route Matcher (Critical)

Standardmäßig führt Next.js die Middleware bei jeder eingehenden HTTP-Anfrage aus. Wird der Matcher nicht korrekt konfiguriert, führt dies zu unnötigen API-Aufrufen für statische Ressourcen (z. B. .png, .css, _next/static). Sie müssen den Standard-Ausschluss-Matcher von Next.js am Ende Ihrer middleware.ts-Datei einfügen, um statische Dateien zu umgehen, wie im Beispiel für die grundlegende Verwendung demonstriert.

2. Fail-Open vs. Fail-Closed Configurations

Standardmäßig ist das Paket auf failOpen: true konfiguriert. Falls die ProxyTracer-API eine Zeitüberschreitung aufweist oder eine Netzwerkstörung eintritt, darf die Anfrage passieren. Dies priorisiert hohe Verfügbarkeit und Benutzerfreundlichkeit. Für besonders sensible Endpunkte (z. B. Finanztransaktionen, Identifikationsprüfungen) wird dringend empfohlen, den Wert auf failOpen: false zu setzen. Dies stellt sicher, dass ein Systemausfall zu einer rigideren Systemsicherheitssperre führt.

3. Edge Node Caching Limitations

Der integrierte Speicher-Cache speichert die IP-Klassifikationsdaten für 5 Minuten pro Edge-Isolate. Da Plattformen wie Vercel und Cloudflare Anfragen über hunderte weltweite Server isoliert verteilen, agiert dieser Cache strikt lokal pro Instanz. Er bietet Schutz gegen Lastspitzen, synchronisiert seinen Status jedoch nicht über Knotenpunktsgrenzen hinweg. Für minimalen API-Verbrauch und eine echte 24-stündige weltweite Cache-Abdeckung wird die Integration einer Redis-Datenbank benötigt.

Sicherheitsrichtlinien

• Stellen Sie sicher, dass Ihr ProxyTracer-API-Schlüssel nicht mit NEXT_PUBLIC_ beginnt. Ist dies der Fall, löst die Middleware einen Fehler aus und beendet den Startvorgang, um Sie davor zu schützen, den Schlüssel versehentlich im Client-Browser zu veröffentlichen.
• Wenn Sie beispielsweise mit einem NGINX-Reverse-Proxy bereitstellen, müssen Sie NGINX so konfigurieren, dass die Header X-Real-IP oder X-Forwarded-For weitergeleitet werden. Anschliessend setzen Sie einfach trustedProxy: "vercel" in den Middleware-Optionen, damit sie diese korrekt auszulesen weiß.

Lizenz

Diese Software ist unter der GNU Affero General Public License v3.0 (AGPLv3) lizenziert. Siehe die LICENSE-Datei für alle Details.