Clerk-integratie

Beveilig Clerk authenticatieroutes tegen VPN's, proxy's en Tor-nodes via Next.js Edge Middleware.

Functies

• Minimale configuratie vereist.
• Volledig compatibel met Vercel Edge, Cloudflare Workers en self-hosted Nginx-omgevingen.
• Blokkeer hoog-risico verkeer op gevoelige routes (bijv. /sign-up) terwijl je expliciet toegang toestaat voor andere routes.
• Native Cloudflare CIDR-validatie voorkomt IP-header spoofing en omzeilingspogingen.
• Twee-Laags Cachesysteem: Ingebouwde in-memory cache om traffic spikes op te vangen, met native ondersteuning voor wereldwijde Redis-integraties.
• Configureerbare Fallback: Hanteer ofwel Fail-Open (prioriteer beschikbaarheid) of Fail-Closed (prioriteer strikte beveiliging) logica tijdens API timeouts.

Installatie

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

Implementatiegids

Vereisten

Deze package vereist Next.js Edge Middleware. Zorg ervoor dat er een middleware.ts (of .js) bestand staat in de root van je project of in de src/ directory.

Basisgebruik

Integreer ProxyTracer met Clerk door clerkMiddleware() te wrappen. Standaard dwingt dit de security check af voor alle routes die matchen met de Next.js middleware-configuratie.

import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // Gebruik geen NEXT_PUBLIC_ prefixen
});
 
export const config = {
  matcher: [
    // Sluit Next.js-internals en alle statische bestanden uit
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Altijd uitvoeren voor API- en tRPC-routes
    '/(api|trpc)(.*)',
  ],
};

Geavanceerde Configuratie

Voor productieomgevingen wordt sterk aanbevolen om fijnmazige controle in te stellen over beschermde routes en specifieke infrastructuur proxy-instellingen te configureren.

1. Granulair routebeleid

Pas specifieke acties toe per route om een balans te vinden tussen beveiliging en gebruikerstoegang.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Definieer routespecifiek toegangsbeleid
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Sta proxies expliciet toe op deze route
  ],
  
  // Globale fallback-URL voor niet-overeenkomende geblokkeerde routes
  fallbackUrl: "/access-denied" 
});

2. Native infrastructuurondersteuning

Configureer IP-extractie op basis van je infrastructuurprovider om CIDR-reeksen veilig te valideren en header spoofing te voorkomen.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Gebruik 'cloudflare' voor Cloudflare, of 'vercel' voor Vercel/Nginx
});

3. Globale Redis-caching (Optioneel)

ProxyTracer bevat een lokale in-memory cache van 5 minuten voor Edge isolates. Om API-verbruik over een gedistribueerde wereldwijde architectuur te optimaliseren, kun je een custom Redis adapter opgeven.

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 }) // Globaal cachen voor 24u
  }
});

API Referentie

Architectuur- & Beveiligingsoverwegingen

Om optimale prestaties en kostenefficiëntie te garanderen bij het gebruik van Next.js Edge Middleware, dien je de volgende richtlijnen in acht te nemen:

1. Next.js Route Matcher (Kritiek)

Standaard voert Next.js middleware uit op elk HTTP-request. Als je de matcher niet correct configureert, resulteert dit in onnodige API-aanroepen voor statische assets (bijv. .png, .css, _next/static). Je moet de standaard Next.js exclusion matcher onderaan je middleware.ts bestand opnemen om statische bestanden over te slaan, zoals getoond in het basisgebruik-voorbeeld.

2. Fail-Open vs. Fail-Closed configuraties

Standaard staat de package geconfigureerd op failOpen: true. Als de ProxyTracer API een timeout geeft of netwerkverbinding faalt, mag het verzoek doorgaan. Dit geeft prioriteit aan hoge beschikbaarheid en gebruikerservaring. Voor zeer gevoelige endpoints (bijv. financiële transacties, identiteitsverificatie) wordt ten zeerste aangeraden om failOpen: false in te stellen. Dit garandeert dat een systeemfout resulteert in een strikte security lockdown.

3. Beperkingen van Edge Node-caching

De ingebouwde in-memory cache bewaart IP-classificatiedata gedurende 5 minuten per Edge isolate. Omdat platforms zoals Vercel en Cloudflare requests distribueren over honderden geïsoleerde nodes wereldwijd, functioneert deze cache strikt lokaal per node. Het biedt effectieve bescherming tegen bursts, maar synchroniseert de state niet globaal. Om API-verbruik te minimaliseren en echte 24-uurs wereldwijde caching af te dwingen, is een Redis-database integratie vereist.

Security Richtlijnen

• Zorg ervoor dat je ProxyTracer API-key niet begint met NEXT_PUBLIC_. Als dit wel het geval is, gooit de middleware bij het opstarten een foutmelding en crasht deze om te voorkomen dat je de key per ongeluk lekt naar de browser.
• Als je host met bijvoorbeeld een Nginx reverse proxy, moet je Nginx configureren om de X-Real-IP of X-Forwarded-For headers door te geven. Zodra dat is gedaan, stel je simpelweg trustedProxy: "vercel" in bij de middleware opties, zodat deze weet hoe de headers correct gelezen moeten worden.

Licentie

Deze software is gelicentieerd onder de GNU Affero General Public License v3.0 (AGPLv3). Raadpleeg het LICENSE bestand voor volledige details.