Integrazione Clerk

Proteggi le route di autenticazione di Clerk da VPN, proxy e nodi Tor tramite Next.js Edge Middleware.

Caratteristiche

• Latenza sub-10ms con supporto del runtime Edge nativo di Next.js.
• Integrazione drop-in compatibile con clerkMiddleware() di @clerk/nextjs.
• Blocco granulare delle route (es. applicazione rigorosa dei controlli su /sign-up).
• Cache in memoria a livello di Edge isolate incorporata per ridurre al minimo le chiamate API di rete.
• Protezione fail-open per garantire che la tua applicazione rimanga accessibile in caso di interruzioni di rete.
• Supporto completo per reverse proxy (Vercel, Cloudflare, NGINX).

Installazione

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

Guida all'Implementazione

Prerequisiti

Questo pacchetto richiede Next.js Edge Middleware. Assicurati che un file middleware.ts (o .js) esista nella root del tuo progetto o all'interno della directory src/.

Utilizzo di Base

Integra ProxyTracer con Clerk eseguendo il wrapping di clerkMiddleware(). Per impostazione predefinita, questo applica il controllo di sicurezza su tutte le route corrispondenti alla configurazione del 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 || "", // Non usare prefissi NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // Escludi i file interni di Next.js e tutti i file statici
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Esegui sempre per le route API e tRPC
    '/(api|trpc)(.*)',
  ],
};

Configurazione Avanzata

Per gli ambienti di produzione, si raccomanda di implementare un controllo granulare sulle route protette e di configurare impostazioni specifiche per il reverse proxy dell'infrastruttura.

1. Policy di Route Granulari

Applica azioni specifiche per route per bilanciare sicurezza e accesso degli utenti.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Definisci policy di accesso specifiche per le route
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Consenti esplicitamente i proxy su questa route
  ],
  
  // URL di fallback globale per le route bloccate non corrispondenti
  fallbackUrl: "/access-denied" 
});

2. Supporto Nativo dell'Infrastruttura

Configura l'estrazione dell'IP in base al tuo provider di infrastruttura per convalidare in modo sicuro i range CIDR e prevenire lo spoofing degli header.

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

3. Caching Globale con Redis (Opzionale)

ProxyTracer include una cache locale in memoria di 5 minuti per gli Edge isolate. Per ottimizzare l'utilizzo dell'API attraverso un'architettura globale distribuita, fornisci un adapter Redis personalizzato.

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 globale per 24h
  }
});

Riferimento API

Considerazioni su Architettura e Sicurezza

Per garantire prestazioni ottimali ed efficienza dei costi durante l'utilizzo di Next.js Edge Middleware, osserva le seguenti linee guida:

1. Matcher delle Route di Next.js (Critico)

Per impostazione predefinita, Next.js esegue il middleware su ogni richiesta HTTP. La mancata configurazione corretta del matcher comporterà invocazioni API non necessarie per le risorse statiche (es. .png, .css, _next/static). Devi includere il matcher di esclusione standard di Next.js in fondo al tuo file middleware.ts per bypassare i file statici, come dimostrato nell'esempio di Utilizzo di Base.

2. Configurazioni Fail-Open vs Fail-Closed

Per impostazione predefinita, il pacchetto è configurato con failOpen: true. Se l'API ProxyTracer va in timeout o la connettività di rete si interrompe, la richiesta può procedere. Questo privilegia l'alta disponibilità e l'esperienza utente. Per endpoint altamente sensibili (es. transazioni finanziarie, verifica dell'identità), si consiglia vivamente di impostare failOpen: false. Ciò garantisce che un guasto del sistema si traduca in un blocco di sicurezza rigoroso.

3. Limitazioni della Cache sui Nodi Edge

La cache in memoria integrata conserva i dati di classificazione IP per 5 minuti per Edge isolate. Poiché piattaforme come Vercel e Cloudflare distribuiscono le richieste su centinaia di nodi isolati a livello globale, questa cache opera rigorosamente a livello locale per ciascun nodo. Fornisce un'efficace protezione contro i picchi ma non sincronizza lo stato a livello globale. Per ridurre al minimo l'utilizzo delle API e imporre un vero caching globale di 24 ore, è necessaria l'integrazione con un database Redis.

Linee Guida sulla Sicurezza

• Assicurati che la tua chiave API ProxyTracer non inizi con NEXT_PUBLIC_. Se lo fa, il middleware genererà un errore e si bloccherà all'avvio per evitare di esporla accidentalmente al browser.
• Se stai distribuendo con, ad esempio, un reverse proxy Nginx, devi configurare Nginx per passare gli header X-Real-IP o X-Forwarded-For. Una volta fatto, imposta semplicemente trustedProxy: "vercel" nelle opzioni del middleware in modo che sappia come leggerli correttamente.

Licenza

Questo software è rilasciato sotto licenza GNU Affero General Public License v3.0 (AGPLv3). Consulta il file LICENSE per i dettagli completi.