تكامل Clerk

تأمين مسارات مصادقة Clerk ضد شبكات VPN والبروكسيات وعقد Tor عبر Next.js Edge Middleware.

الميزات

• يتطلب الحد الأدنى من التهيئة.
• متوافق تماماً مع Vercel Edge و Cloudflare Workers وبيئات Nginx ذاتية الاستضافة.
• حظر حركة المرور عالية الخطورة على المسارات الحساسة (مثل /sign-up) مع السماح بالوصول صراحة إلى مسارات أخرى.
• التحقق الأصيل من نطاقات Cloudflare CIDR يمنع تزييف ترويسات IP ومحاولات التحايل.
• نظام تخزين مؤقت ثنائي الطبقات: ذاكرة تخزين مؤقت مدمجة للتعامل مع الارتفاعات المفاجئة، مع دعم أصيل للتكامل مع خوادم Redis العالمية.
• سلوك احتياطي قابل للضبط: فرض منطق التمرير عند الفشل (Fail-Open) لإعطاء الأولوية للتوفر، أو الإغلاق عند الفشل (Fail-Closed) لإعطاء الأولوية للأمان الصارم عند انقضاء مهلة API.

التثبيت

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

دليل التطبيق

المتطلبات الأساسية

تتطلب هذه الحزمة Next.js Edge Middleware. تأكد من وجود ملف middleware.ts (أو .js) في جذر مشروعك أو داخل مجلد src/.

الاستخدام الأساسي

ادمج ProxyTracer مع Clerk بتغليف clerkMiddleware(). بشكل افتراضي، يفرض هذا الفحص الأمني عبر جميع المسارات المتطابقة مع تهيئة البرمجية الوسيطة في Next.js.

import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // لا تستخدم بادئات NEXT_PUBLIC_
});
 
export const config = {
  matcher: [
    // استبعاد ملفات Next.js الداخلية وجميع الملفات الثابتة
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // التنفيذ دائماً لمسارات API و tRPC
    '/(api|trpc)(.*)',
  ],
};

التكوين المتقدم

بالنسبة لبيئات الإنتاج، يُوصى بتطبيق تحكم دقيق على المسارات المحمية وتهيئة إعدادات بروكسي البنية التحتية بدقة.

1. سياسات المسارات الدقيقة

تطبيق إجراءات محددة لكل مسار لتحقيق التوازن بين الأمان ووصول المستخدمين.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // تحديد سياسات وصول خاصة بكل مسار
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // السماح صراحة بالبروكسيات في هذا المسار
  ],
  
  // رابط احتياطي عالمي للمسارات المحظورة غير المتطابقة
  fallbackUrl: "/access-denied" 
});

2. دعم أصيل للبنية التحتية

تهيئة استخراج IP بناءً على مزود بنيتك التحتية للتحقق الآمن من نطاقات CIDR ومنع تزييف الترويسات.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // استخدم 'cloudflare' لـ Cloudflare، أو 'vercel' لـ Vercel/Nginx
});

3. تخزين مؤقت عالمي عبر Redis (اختياري)

يتضمن ProxyTracer ذاكرة تخزين مؤقت محلية لمدة 5 دقائق لعزلات الحافة. لتحسين استهلاك API عبر بنية معمارية عالمية موزعة، وفر مهايئ 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 }) // التخزين المؤقت عالمياً لمدة 24 ساعة
  }
});

مرجع API

اعتبارات البنية المعمارية والأمان

لضمان الأداء الأمثل وفعالية التكلفة أثناء استخدام برمجية Next.js Edge الوسيطة، يرجى مراعاة الإرشادات التالية:

1. مطابق مسارات Next.js (هام)

بشكل افتراضي، تنفذ Next.js البرمجية الوسيطة في كل طلب HTTP. سيؤدي الفشل في تهيئة المطابق (matcher) بشكل صحيح إلى استدعاءات API غير ضرورية للأصول الثابتة (مثل .png و .css و _next/static). يجب عليك تضمين مطابق استبعاد Next.js القياسي في أسفل ملف middleware.ts لتجاوز الملفات الثابتة، كما هو موضح في مثال الاستخدام الأساسي.

2. تكوينات Fail-Open مقابل Fail-Closed

افتراضياً، تم تهيئة الحزمة على failOpen: true. إذا انقضت مهلة ProxyTracer API أو فشل الاتصال بالشبكة، يُسمح للطلب بالمتابعة، مما يمنح الأولوية للجاهزية وتجربة المستخدم. بالنسبة لنقاط النهاية الحساسة للغاية (مثل المعاملات المالية أو التحقق من الهوية)، يُنصح بشدة بضبط failOpen: false لضمان إغلاق أمني صارم عند حدوث عطل.

3. قيود التخزين المؤقت في عقد الحافة

تحتفظ الذاكرة المؤقتة المدمجة ببيانات تصنيف IP لمدة 5 دقائق لكل عزلة حافة (Edge isolate). نظراً لأن منصات مثل Vercel و Cloudflare توزع الطلبات عبر مئات العقد المعزولة عالمياً، فإن هذه الذاكرة تعمل محلياً فقط لكل عقدة. إنها توفر حماية فعالة من الارتفاعات اللحظية ولكنها لا تزامن الحالة عالمياً. لتقليل استخدام API وفرض تخزين مؤقت حقيقي لمدة 24 ساعة، يلزم دمج قاعدة بيانات Redis.

إرشادات الأمان

• تأكد من أن مفتاح ProxyTracer API الخاص بك لا يبدأ بـ NEXT_PUBLIC_. إذا كان كذلك، ستلقي البرمجية الوسيطة خطأ وتتعطل عند بدء التشغيل لمنع تسريبه عن طريق الخطأ إلى المتصفح.
• إذا كنت تنشر باستخدام بروكسي عكسي مثل Nginx، فأنت بحاجة لتهيئة Nginx لتمرير ترويسات X-Real-IP أو X-Forwarded-For. بمجرد الانتهاء، اضبط trustedProxy: "vercel" في خيارات البرمجية الوسيطة حتى تتمكن من قراءتها بشكل صحيح.

الترخيص

هذا البرنامج مرخص بموجب رخصة جنو أفيرو العمومية الإصدار 3.0 (AGPLv3). راجع ملف LICENSE للتفاصيل الكاملة.