Integracja z Clerk

Zabezpieczaj trasy uwierzytelniania Clerk przed sieciami VPN, serwerami proxy i węzłami Tor za pomocą Next.js Edge Middleware.

Funkcje

• Wymaga minimalnej konfiguracji.
• W pełni kompatybilny ze środowiskami Vercel Edge, Cloudflare Workers oraz własnymi instalacjami NGINX.
• Blokuj ruch wysokiego ryzyka na wrażliwych trasach (np. /sign-up), jednocześnie jawnie zezwalając na dostęp do pozostałych.
• Natywna walidacja zakresów CIDR Cloudflare zapobiega próbom fałszowania nagłówków IP i omijania zabezpieczeń.
• Dwuwarstwowy system pamięci podręcznej: Wbudowany cache w RAM do łagodzenia nagłych skoków ruchu z natywnym wsparciem dla globalnej integracji z Redis.
• Konfigurowalny tryb awaryjny: Wymuś logikę Fail-Open (priorytet dostępności) lub Fail-Closed (priorytet ścisłego bezpieczeństwa) podczas przekroczenia limitu czasu API.

Instalacja

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

Przewodnik po implementacji

Wymagania wstępne

Ten pakiet wymaga środowiska Next.js Edge Middleware. Upewnij się, że plik middleware.ts (lub .js) znajduje się w głównym katalogu projektu lub wewnątrz katalogu src/.

Podstawowe użycie

Zintegruj ProxyTracer z Clerk, opakowując clerkMiddleware(). Domyślnie wymusza to weryfikację bezpieczeństwa na wszystkich trasach dopasowanych przez konfigurację 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 || "", // Nie używaj prefiksów NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // Wyklucz pliki wewnętrzne Next.js oraz wszystkie zasoby statyczne
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Zawsze wykonuj dla tras API oraz tRPC
    '/(api|trpc)(.*)',
  ],
};

Zaawansowana konfiguracja

W środowiskach produkcyjnych zaleca się wdrożenie szczegółowej kontroli nad chronionymi trasami oraz skonfigurowanie dedykowanych ustawień reverse proxy dla Twojej infrastruktury.

1. Szczegółowe reguły tras

Zastosuj zróżnicowane akcje w zależności od trasy, aby zachować równowagę między bezpieczeństwem a dostępnością dla użytkowników.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Zdefiniuj reguły dostępu dla poszczególnych tras
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Wyraźnie zezwól na proxy na tej trasie
  ],
  
  // Globalny adres URL przekierowania dla niedopasowanych zablokowanych tras
  fallbackUrl: "/access-denied" 
});

2. Natywne wsparcie dla infrastruktury

Skonfiguruj wyodrębnianie adresów IP w oparciu o dostawcę infrastruktury, aby bezpiecznie weryfikować zakresy CIDR i zapobiegać fałszowaniu nagłówków (header spoofing).

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Użyj 'cloudflare' dla Cloudflare lub 'vercel' dla Vercel/Nginx
});

3. Globalne buforowanie w Redis (Opcjonalnie)

ProxyTracer zawiera 5-minutową lokalną pamięć podręczną w pamięci RAM dla instancji Edge (isolates). Aby zoptymalizować zużycie API w rozproszonej architekturze globalnej, możesz dostarczyć własny adapter Redis.

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'uj globalnie na 24h
  }
});

Dokumentacja API

Architektura i kwestie bezpieczeństwa

Aby zapewnić optymalną wydajność i efektywność kosztową podczas korzystania z Next.js Edge Middleware, przestrzegaj poniższych zasad:

1. Matcher tras Next.js (Krytyczne)

Domyślnie Next.js uruchamia middleware przy każdym żądaniu HTTP. Brak poprawnej konfiguracji matchera spowoduje niepotrzebne wywołania API dla plików statycznych (np. .png, .css, _next/static). Musisz dołączyć standardowy matcher wykluczeń Next.js na dole pliku middleware.ts, aby omijać pliki statyczne, jak pokazano w przykładzie podstawowym.

2. Konfiguracje Fail-Open a Fail-Closed

Domyślnie pakiet jest skonfigurowany w trybie failOpen: true. Jeśli wystąpi timeout API ProxyTracer lub awaria sieci, żądanie zostanie przepuszczone. Priorytetem jest wysoka dostępność i komfort użytkowników. W przypadku krytycznych endpointów (np. transakcji finansowych, weryfikacji tożsamości) zdecydowanie zaleca się ustawienie failOpen: false. Zapewnia to restrykcyjną blokadę w razie niedostępności usług zewnętrznych.

3. Ograniczenia buforowania w węzłach Edge

Wbudowana pamięć podręczna przechowuje wyniki klasyfikacji IP przez 5 minut na poziomie instancji Edge. Ponieważ platformy takie jak Vercel i Cloudflare rozpraszają żądania pomiędzy setki węzłów na całym świecie, cache ten działa lokalnie na każdym węźle. Stanowi skuteczną ochronę przed nagłymi skokami zapytań (bursts), lecz nie synchronizuje stanu globalnie. Aby zminimalizować zużycie API i wymusić 24-godzinny globalny cache, zalecana jest integracja z bazą danych Redis.

Zalecenia dotyczące bezpieczeństwa

• Upewnij się, że zmienna zawierająca klucz API ProxyTracer nie zaczyna się od prefiksu NEXT_PUBLIC_. Jeśli tak się stanie, middleware zgłosi błąd i zatrzyma start aplikacji, aby zapobiec przypadkowemu wyciekowi klucza do przeglądarki klienta.
• Jeśli wdrażasz aplikację za reverse proxy NGINX, skonfiguruj NGINX tak, aby przekazywał nagłówki X-Real-IP lub X-Forwarded-For. Następnie po prostu ustaw trustedProxy: "vercel" w opcjach middleware, aby poprawnie odczytywać te nagłówki.

Licencja

To oprogramowanie jest objęte licencją GNU Affero General Public License v3.0 (AGPLv3). Pełną treść licencji znajdziesz w pliku LICENSE.