Интеграция с Clerk

Защитите маршруты аутентификации Clerk от VPN, прокси и узлов Tor с помощью Next.js Edge Middleware.

Возможности

• Требует минимальной конфигурации.
• Полностью совместима с Vercel Edge, Cloudflare Workers и self-hosted средами Nginx.
• Блокируйте высокорисковый трафик на конфиденциальных маршрутах (например, /sign-up), явно разрешая доступ к остальным.
• Встроенная проверка CIDR-диапазонов Cloudflare предотвращает подмену IP-заголовков и попытки обхода.
• Двухуровневая система кэширования: встроенный in-memory кэш для сглаживания всплесков трафика и нативная поддержка глобальных интеграций Redis.
• Настраиваемое поведение при сбоях (Fallback): при таймаутах API применяйте логику Fail-Open (приоритет доступности) или Fail-Closed (строгий приоритет безопасности).

Установка

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 middleware.

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)(.*)',
  ],
};

Расширенная конфигурация

Для production-сред рекомендуется настроить точечный контроль защищенных маршрутов и параметры для инфраструктурного прокси.

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" }, // Явно разрешить прокси на этом маршруте
  ],
  
  // Глобальный резервный URL для несовпадающих заблокированных маршрутов
  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-минутный локальный кэш в оперативной памяти для Edge-изолятов. Чтобы оптимизировать использование 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 Middleware соблюдайте следующие правила:

1. Фильтр маршрутов Next.js (Критично)

По умолчанию Next.js запускает middleware для каждого HTTP-запроса. Если не настроить фильтр маршрутов (matcher) должным образом, это приведет к ненужным API-вызовам для статических файлов (например, .png, .css, _next/static). Вы обязаны включить стандартное исключение Next.js в нижней части вашего файла middleware.ts, чтобы пропускать статические файлы, как показано в примере базового использования.

2. Конфигурации Fail-Open и Fail-Closed

По умолчанию пакет настроен на failOpen: true. В случае таймаута API ProxyTracer или сбоя сети запрос будет пропущен. Это ставит в приоритет высокую доступность и пользовательский опыт. Для крайне критичных маршрутов (например, финансовых транзакций, верификации личности) настоятельно рекомендуется установить failOpen: false. Это гарантирует, что сбой в системе приведет к строгой блокировке.

3. Ограничения кэширования на узлах Edge

Встроенный in-memory кэш сохраняет результаты классификации IP на 5 минут для каждого Edge-изолята. Поскольку платформы вроде Vercel и Cloudflare распределяют запросы по сотням изолированных узлов по всему миру, этот кэш работает строго локально на каждом узле. Он обеспечивает отличную защиту от всплесков, но не синхронизирует состояние глобально. Чтобы минимизировать использование API и обеспечить настоящее глобальное кэширование на 24 часа, требуется интеграция с Redis.

Рекомендации по безопасности

• Убедитесь, что ваш API-ключ ProxyTracer не начинается с NEXT_PUBLIC_. Если это так, middleware выдаст ошибку и завершит работу при запуске, чтобы уберечь вас от случайной утечки ключа в браузер.
• Если вы развертываете приложение, скажем, за reverse proxy Nginx, вам необходимо настроить Nginx на передачу заголовков X-Real-IP или X-Forwarded-For. После этого просто установите trustedProxy: "vercel" в параметрах middleware, чтобы он знал, как правильно их считывать.

Лицензия

Это программное обеспечение лицензируется на условиях GNU Affero General Public License v3.0 (AGPLv3). Подробности смотрите в файле LICENSE.