Clerk-Integration

Sichern Sie Clerk-Authentifizierungsrouten gegen VPNs, Proxys und Tor-Knoten über Next.js Edge Middleware ab.

Funktionen

• Minimale Konfiguration erforderlich.
• Vollständig kompatibel mit Vercel Edge, Cloudflare Workers und selbst gehosteten Nginx-Umgebungen.
• Blockieren Sie risikoreichen Traffic auf sensiblen Routen (z. B. /sign-up), während der Zugriff auf andere Routen explizit erlaubt bleibt.
• Native Cloudflare-CIDR-Validierung verhindert IP-Header-Spoofing und Umgehungsversuche.
• Zweistufiges Caching-System: Integrierter Speicher-Cache zur Abfederung von Lastspitzen mit nativer Unterstützung für globale Redis-Integrationen.
• Konfigurierbares Fallback: Erzwingen Sie bei API-Timeouts wahlweise Fail-Open (Verfügbarkeit priorisieren) oder Fail-Closed (strikte Sicherheit priorisieren).

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 || "", // Verwenden Sie keine NEXT_PUBLIC_-Präfixe
});
 
export const config = {
  matcher: [
    // Next.js-Interna und alle statischen Dateien ausschließen
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Immer für API- und tRPC-Routen ausführen
    '/(api|trpc)(.*)',
  ],
};

Erweiterte Konfiguration

Für Produktionsumgebungen wird empfohlen, eine granulare Steuerung über geschützte Routen zu implementieren und spezifische Infrastruktur-Proxy-Einstellungen zu konfigurieren.

1. Granulare Routen-Richtlinien

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 || "",
  
  // Routenspezifische Zugriffsrichtlinien definieren
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Proxys auf dieser Route explizit zulassen
  ],
  
  // Globale Fallback-URL für nicht zugeordnete blockierte Routen
  fallbackUrl: "/access-denied" 
});

2. Native Infrastruktur-Unterstützung

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", // Verwenden Sie 'cloudflare' für Cloudflare oder 'vercel' für Vercel/Nginx
});

3. Globales 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 }) // Für 24h global zwischenspeichern
  }
});

API-Referenz

Architektur & Sicherheitshinweise

Um eine optimale Performance und Kosteneffizienz bei der Nutzung der Next.js-Edge-Middleware sicherzustellen, beachten Sie bitte die folgenden Richtlinien:

1. Next.js Route Matcher (Kritisch)

Standardmäßig führt Next.js die Middleware bei jeder HTTP-Anfrage aus. Das Fehlen einer korrekten Matcher-Konfiguration führt zu unnötigen API-Aufrufen für statische Assets (z. B. .png, .css, _next/static). Sie müssen den Standard-Next.js-Ausschluss-Matcher am Ende Ihrer middleware.ts-Datei einbinden, um statische Dateien zu umgehen, wie im Beispiel zur grundlegenden Nutzung gezeigt.

2. Fail-Open vs. Fail-Closed Konfigurationen

Standardmäßig ist das Paket auf failOpen: true konfiguriert. Falls das ProxyTracer-API-Timeout erreicht wird oder die Netzwerkverbindung fehlschlägt, darf die Anfrage passieren. Dies priorisiert hohe Verfügbarkeit und Nutzererfahrung. Bei hochsensiblen Endpunkten (z. B. Finanztransaktionen, Identitätsprüfungen) wird dringend empfohlen, failOpen: false zu setzen. Dadurch führt ein Systemausfall zu einem strikten Sicherheits-Lockdown.

3. Einschränkungen beim Caching auf Edge-Knoten

Der integrierte Arbeitsspeicher-Cache speichert die IP-Klassifizierungsdaten für 5 Minuten pro Edge-Isolat. Da Plattformen wie Vercel und Cloudflare Anfragen über hunderte isolierte Knoten weltweit verteilen, agiert dieser Cache lokal pro Knoten. Er bietet einen wirksamen Schutz bei Traffic-Spitzen, synchronisiert den Status jedoch nicht global. Um die API-Nutzung zu minimieren und ein echtes, globales 24-Stunden-Caching durchzusetzen, ist die Integration einer Redis-Datenbank erforderlich.

Sicherheitsrichtlinien

• Stellen Sie sicher, dass Ihr ProxyTracer-API-Schlüssel nicht mit NEXT_PUBLIC_ beginnt. Wenn doch, wird die Middleware einen Fehler werfen und beim Start abstürzen, um Sie davor zu bewahren, den Schlüssel versehentlich im Browser offenzulegen.
• Wenn Sie beispielsweise über einen Nginx-Reverse-Proxy bereitstellen, müssen Sie Nginx so konfigurieren, dass die Header X-Real-IP oder X-Forwarded-For weitergeleitet werden. Setzen Sie danach in den Middleware-Optionen trustedProxy: "vercel", damit die Header korrekt ausgelesen werden.

Lizenz

Diese Software ist unter der GNU Affero General Public License v3.0 (AGPLv3) lizenziert. Weitere Details finden Sie in der LICENSE-Datei.