Clerk 연동

Next.js Edge Middleware를 통해 VPN, 프록시 및 Tor 노드로부터 Clerk 인증 라우트를 보호하세요.

특징

• 최소한의 구성이 필요합니다.
• Vercel Edge, Cloudflare Workers 및 자체 호스팅 Nginx 환경과 완벽하게 호환됩니다.
• 민감한 경로(예: /sign-up)에서 고위험 트래픽을 차단하는 동시에 다른 사용자의 액세스를 명시적으로 허용합니다.
• 기본 Cloudflare CIDR 검증은 IP 헤더 스푸핑 및 우회 시도를 방지합니다.
• 2계층 캐싱 시스템: 글로벌 Redis 통합을 기본적으로 지원하는 버스트 트래픽 완화를 위한 내장형 메모리 캐시입니다.
• 구성 가능한 폴백: 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/ 디렉터리에 있는지 확인하세요.

기본 사용법

clerkMiddleware()를 래핑하여 ProxyTracer를 Clerk와 통합합니다. 기본적으로 이는 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" }, // 이 라우트에서 프록시를 명시적으로 허용하십시오
  ],
  
  // 일치하지 않는 차단된 라우트에 대한 전역 폴백 URL
  fallbackUrl: "/access-denied" 
});

2. 인프라 네이티브 지원

인프라 공급자를 기반으로 IP 추출을 구성하여 CIDR 범위를 안전하게 검증하고 헤더 스푸핑을 방지하세요.

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Cloudflare의 경우 'cloudflare'를 사용하거나 Vercel/Nginx의 경우 'vercel'을 사용하십시오
});

3. 글로벌 Redis 캐싱 (선택 사항)

ProxyTracer에는 Edge 격리를 위한 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 Middleware를 활용하면서 최적의 성능과 비용 효율성을 보장하려면 다음 지침을 준수하십시오.

1. Next.js 경로 매처 (중요)

기본적으로 Next.js는 모든 HTTP 요청에서 미들웨어를 실행합니다. 매처를 적절하게 구성하지 못하면 정적 자산(예: .png, .css, _next/static)에 대해 불필요한 API 호출이 발생합니다. 기본 사용법 예제에서 설명한 것처럼 정적 파일을 우회하려면 middleware.ts 파일 하단에 표준 Next.js 제외 일치자를 포함해야 합니다.

2. Fail-Open 대 Fail-Closed 구성

기본적으로 패키지는 failOpen: true로 구성됩니다. ProxyTracer API 시간이 초과되거나 네트워크 연결이 실패하면 요청 진행이 허용됩니다. 이는 고가용성과 사용자 경험을 우선시합니다. 매우 민감한 엔드포인트(예: 금융 거래, 신원 확인)의 경우 'failOpen: false'를 설정하는 것이 좋습니다. 이렇게 하면 시스템 오류로 인해 엄격한 보안 잠금이 발생합니다.

3. 엣지 노드 캐싱 제한 사항

내장 메모리 캐시는 Edge 격리당 5분 동안 IP 분류 데이터를 유지합니다. Vercel 및 Cloudflare와 같은 플랫폼은 요청을 전 세계적으로 수백 개의 격리된 노드에 분산하기 때문에 이 캐시는 엄격하게 노드별로 로컬로 작동합니다. 효과적인 버스트 보호를 제공하지만 전역적으로 상태를 동기화하지는 않습니다. API 사용량을 최소화하고 진정한 24시간 글로벌 캐싱을 적용하려면 Redis 데이터베이스 통합이 필요합니다.

보안 지침

• ProxyTracer API 키가 'NEXT_PUBLIC_'으로 시작하지 않는지 확인하세요. 만약 그렇다면, 미들웨어는 실수로 브라우저에 유출되는 것을 방지하기 위해 시작 시 오류와 충돌을 발생시킵니다.
• 예를 들어 Nginx 역방향 프록시를 사용하여 배포하는 경우 'X-Real-IP' 또는 'X-Forwarded-For' 헤더를 전달하도록 Nginx를 구성해야 합니다. 완료되면 미들웨어 옵션에서 trustedProxy: "vercel"을 설정하여 올바르게 읽는 방법을 알 수 있도록 하세요.

라이센스

이 소프트웨어는 GNU Affero General Public License v3.0(AGPLv3)에 따라 라이센스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.