Clerk連携

Clerk 認証ワークフローを保護し、不正なアカウント作成を防止しましょう。

機能

• サインアップおよびログインエンドポイントにおける VPN、データセンタープロキシ、Tor 出口ノードを瞬時に検出。
• Clerk の clerkMiddleware() ラッパー内で直接実行される、完全な Edge Runtime 互換の判定処理。
• 機密性の高いルート（例: /sign-up）上の高リスクなトラフィックをブロックしつつ、他のルートへのアクセスは明示的に許可。
• インメモリ処理による完全ノーログ保証（IP アドレスはログとして保存されず、即座に破棄されます）。
• 500ms の厳格なフェイルオープンタイムアウトにより、API に障害が発生した場合でもユーザーのサインインを妨げません。
• Next.js 13、14、15（App Router および Pages Router）を完全サポート。

インストール

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

実装ガイド

前提条件

このパッケージには Next.js Edge Middleware が必要です。プロジェクトのルートまたは src/ ディレクトリ内に middleware.ts（または .js）ファイルが存在することを確認してください。

基本的な使い方

この構成では、clerkMiddleware 内で ProxyTracer をラップします。/sign-up または /api/ へのすべてのリクエストを検査し、VPN またはプロキシが検出された場合は直ちに 403 Forbidden を返します。

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

高度な設定

本番環境のエンタープライズデプロイメント向けに、ルートごとのカスタムポリシー、フェイルオーバーハンドリング、Cloudflare 統合を含む堅牢な構成を提供します:

1. きめ細かなルートポリシー

特定のルートに対してプロキシ接続を明示的に許可または拒否します。たとえば、公開マーケティングページや /sign-in ではプロキシを許可しつつ、/sign-up や高リスクな決済 API では厳格にブロックします。

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. インフラネイティブのサポート

Vercel のネイティブな x-real-ip、Cloudflare の cf-connecting-ip、または標準の x-forwarded-for ヘッダーからクライアント IP を自動的かつ安全に解決します。

export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Cloudflareには'cloudflare'を、Vercel/Nginxには'vercel'を使用
});

3. グローバルRedisキャッシュ（任意）

同じ IP アドレスに対する重複した API クエリを削減するために、Upstash または Redis を使用した任意のエッジキャッシュレイヤーを導入できます（TTL: 24時間）。

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リファレンス

アーキテクチャとセキュリティに関する考慮事項

Clerk 認証フローと Edge Middleware を連携させる際は、以下のベストプラクティスを遵守してください:

1. Next.js Route Matcher（重要）

Next.js の内部アセット（_next）、静的ファイル、ファビコンがプロキシチェックを実行しないよう、middleware.ts の末尾にある matcher 設定で適切に除外してください。これにより不要な API クレジット消費を防ぎます。

2. フェイルオープン vs フェイルクローズ設定

提供されているスニペットは フェイルオープン（fail-open） ポリシーを実装しています。ネットワークタイムアウトや API の一時的な障害が発生した場合、正規ユーザーのログインを妨げないようリクエストを通過させます。最高レベルのセキュリティ要件がある場合は、ブロックするように変更してください。

3. エッジノードキャッシュの制限事項

Vercel Edge Functions はステートレスです。インメモリの Map キャッシュは個々のエッジノードのライフサイクル内に限定されます。グローバルなキャッシュ共有が必要な場合は、分散キャッシュ（Upstash Redis など）をご利用ください。

セキュリティガイドライン

• 悪意あるユーザーが偽造したヘッダー（X-Forwarded-For: 1.1.1.1 など）を送信して IP を偽装できないよう、必ず信頼できるプロキシ（Cloudflare、Vercel 等）の背後で実行してください。
• PROXYTRACER_API_KEY をクライアントサイドのコードに露出させないでください。Next.js で NEXT_PUBLIC_ プレフィックスを付けてはいけません。このキーは常にサーバーサイドまたはエッジミドルウェア内でのみ使用してください。

ライセンス

この統合スニペットは MIT ライセンスの下で提供されており、商用および非商用プロジェクトで自由にご利用いただけます。