Clerk Entegrasyonu

Next.js Edge Middleware ile Clerk kimlik doğrulama rotalarını VPN'lere, proxy'lere ve Tor düğümlerine karşı koruyun.

Özellikler

• Minimum yapılandırma gerektirir.
• Vercel Edge, Cloudflare Workers ve bağımsız barındırılan Nginx ortamlarıyla tam uyumludur.
• Hassas rotalardaki (ör. /sign-up) yüksek riskli trafiği engellerken diğer rotalara açıkça erişim izni verin.
• Yerel Cloudflare CIDR doğrulaması, sahte IP başlığı (header spoofing) ve atlatma girişimlerini önler.
• İki Katmanlı Önbellek Sistemi: Ani trafik artışlarını azaltmak için yerleşik bellek içi önbellek ve küresel Redis entegrasyonları için yerel destek.
• Yapılandırılabilir Geri Dönüş: API zaman aşımları sırasında Fail-Open (erişilebilirliğe öncelik ver) veya Fail-Closed (katı güvenliğe öncelik ver) mantığını uygulayın.

Kurulum

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

Uygulama Kılavuzu

Ön Koşullar

Bu paket Next.js Edge Middleware gerektirir. Projenizin kök dizininde veya src/ dizini içinde bir middleware.ts (veya .js) dosyasının bulunduğundan emin olun.

Temel Kullanım

clerkMiddleware() fonksiyonunu sarmalayarak ProxyTracer'ı Clerk ile entegre edin. Varsayılan olarak bu, Next.js middleware yapılandırmasıyla eşleşen tüm rotalarda güvenlik kontrolünü zorunlu kılar.

import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // NEXT_PUBLIC_ ön eklerini kullanmayın
});
 
export const config = {
  matcher: [
    // Next.js dahili bileşenlerini ve tüm statik dosyaları hariç tutun
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // API ve tRPC rotaları için her zaman çalıştırın
    '/(api|trpc)(.*)',
  ],
};

Gelişmiş Yapılandırma

Üretim ortamları için, korunan rotalar üzerinde ayrıntılı kontrol uygulanması ve altyapıya özel proxy ayarlarının yapılandırılması önerilir.

1. Ayrıntılı Rota İlkeleri

Güvenliği ve kullanıcı erişimini dengelemek için rota başına belirli eylemler uygulayın.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // Rotaya özel erişim ilkeleri tanımlayın
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // Bu rotada proxy'lere açıkça izin verin
  ],
  
  // Eşleşmeyen engellenen rotalar için genel geri dönüş URL'si
  fallbackUrl: "/access-denied" 
});

2. Altyapı Yerel Desteği

CIDR aralıklarını güvenli bir şekilde doğrulamak ve başlık sahteciliğini önlemek için IP çıkarmayı altyapı sağlayıcınıza göre yapılandırın.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Cloudflare için 'cloudflare' veya Vercel/Nginx için 'vercel' kullanın
});

3. Küresel Redis Önbellekleme (İsteğe Bağlı)

ProxyTracer, Edge izolatları için 5 dakikalık yerel bellek önbelleği içerir. Dağıtılmış küresel bir mimaride API kullanımını optimize etmek için özel bir Redis adaptörü sağlayın.

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 }) // 24 saat boyunca global olarak önbelleğe alın
  }
});

API Referansı

Mimari ve Güvenlik Hususları

Next.js Edge Middleware kullanırken en yüksek performansı ve maliyet verimliliğini sağlamak için lütfen aşağıdaki yönergelere uyun:

1. Next.js Rota Eşleştiricisi (Kritik)

Next.js varsayılan olarak her HTTP isteğinde middleware'i çalıştırır. Eşleştiricinin (matcher) doğru şekilde yapılandırılmaması, statik varlıklar (ör. .png, .css, _next/static) için gereksiz API çağrılarına neden olur. Temel Kullanım örneğinde gösterildiği gibi, statik dosyaları atlamak için standart Next.js hariç tutma eşleştiricisini middleware.ts dosyanızın altına eklemeniz gerekir.

2. Fail-Open ve Fail-Closed Yapılandırmaları

Varsayılan olarak paket failOpen: true olarak yapılandırılmıştır. ProxyTracer API zaman aşımına uğrarsa veya ağ bağlantısı kesilirse isteğin devam etmesine izin verilir. Bu, yüksek erişilebilirliğe ve kullanıcı deneyimine öncelik verir. Son derece hassas uç noktalar için (ör. finansal işlemler, kimlik doğrulama), failOpen: false ayarının yapılması önemle tavsiye edilir. Bu, sistem arızalarında katı bir güvenlik kilitlemesi sağlar.

3. Edge Düğümü Önbellek Sınırlamaları

Yerleşik bellek önbelleği, IP sınıflandırma verilerini Edge izolatı başına 5 dakika boyunca saklar. Vercel ve Cloudflare gibi platformlar istekleri küresel olarak yüzlerce izole düğüme dağıttığından, bu önbellek yalnızca düğüm başına yerel olarak çalışır. Etkili ani trafik koruması sağlar ancak durumu küresel olarak senkronize etmez. API kullanımını en aza indirmek ve 24 saatlik gerçek küresel önbelleğe alma uygulamak için Redis veritabanı entegrasyonu gereklidir.

Güvenlik Yönergeleri

• ProxyTracer API anahtarınızın NEXT_PUBLIC_ ile başlamadığından emin olun. Böyle bir durumda middleware bir hata fırlatacak ve anahtarın yanlışlıkla tarayıcıya sızmasını önlemek için başlangıçta çökecektir.
• Örneğin bir Nginx ters proxy ile dağıtım yapıyorsanız, Nginx'i X-Real-IP veya X-Forwarded-For başlıklarını iletecek şekilde yapılandırmanız gerekir. Bu yapıldıktan sonra, middleware seçeneklerinde trustedProxy: "vercel" ayarlamanız yeterlidir; böylece başlıkları doğru şekilde okuyacaktır.

Lisans

Bu yazılım GNU Affero Genel Kamu Lisansı v3.0 (AGPLv3) kapsamında lisanslanmıştır. Tüm ayrıntılar için LICENSE dosyasına bakın.