Next.js - Ribaunt

Bu kılavuz, bir Next.js uygulamasına iki Ribaunt CAPTCHA API yolunu nasıl ekleyeceğinizi gösterir — biri challenge’ları yayınlamak ve diğeri çözümleri doğrulamak için. Hem App Router (app/ dizini, Next.js 13+) hem de Pages Router (pages/api/, Next.js 12 ve altı) aşağıda ele alınmıştır.

RIBAUNT_SECRET değerini asla NEXT_PUBLIC_ öneki ile kullanmayın. Bu şekilde önek alan değişkenler derleme zamanında istemciye paketlenir ve her tarayıcıya açılır. Bu değeri yalnızca sunucu tarafında tutun.

Ortam kurulumu

Gizli anahtarınızı .env.local dosyasına ekleyin. Next.js bu dosyayı otomatik olarak yükler ve değerlerini yalnızca sunucu tarafında tutar:

# .env.local — server-side only
RIBAUNT_SECRET="your_very_strong_random_secret_string"

App Router (Next.js 13+)

Bu dosyaları app/api/captcha/challenge/route.ts ve app/api/captcha/verify/route.ts konumlarına yerleştirin.

Aşağıda gösterilen iki yol işleyici dosyasını oluşturun. Her dosya adlandırılmış bir HTTP metodu işlevi (GET veya POST) dışa aktarır — App Router kuralı budur.

challenge/route.ts
verify/route.ts

import { NextResponse } from 'next/server';
import { createChallenge } from 'ribaunt';

export async function GET() {
  try {
    const challenges = createChallenge(5, 4, 60);
    return NextResponse.json({ challenges });
  } catch (error) {
    return NextResponse.json({ error: 'Failed to generate challenge' }, { status: 500 });
  }
}

createChallenge(5, 4, 60), her biri 60 saniye geçerli olan, zorluk seviyesi 5 olan 4 imzalı challenge tokeni oluşturur. İşlev bir JWT dizeleri dizisi döndürür; bunu { challenges } içine sarmak, Ribaunt widget’ının beklediği yanıt sözleşmesiyle eşleşir.

import { NextResponse } from 'next/server';
import { verifySolution } from 'ribaunt';

export async function POST(req: Request) {
  const { tokens, solutions } = await req.json();

  if (!tokens || !solutions) {
    return NextResponse.json(
      { success: false, error: 'Missing tokens or solutions' },
      { status: 400 }
    );
  }

  const isValid = await verifySolution(tokens, solutions, {
    onWarning: (warning) => console.log('captcha warning', warning.reason),
  });

  if (isValid) {
    return NextResponse.json({ success: true });
  }
  return NextResponse.json(
    { success: false, error: 'Invalid CAPTCHA solution' },
    { status: 400 }
  );
}

verifySolution, JWT imzasını doğrular, her hash’in gerekli zorluğu karşıladığını kontrol eder, süresi dolmuş tokenleri reddeder ve (varsayılan olarak) mevcut süreç içinde token tekrar oynatmasını engeller. Bir Promise<boolean> döndürür.

Pages Router (Next.js 12 ve altı)

pages/api/ dizinini kullanıyorsanız, aşağıdaki iki işleyici dosyasını oluşturun. Her biri NextApiRequest ve NextApiResponse alan varsayılan bir asenkron işlev dışa aktarır.

pages/api/captcha/challenge.ts
pages/api/captcha/verify.ts

import type { NextApiRequest, NextApiResponse } from 'next';
import { createChallenge } from 'ribaunt';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'GET') {
    return res.status(405).json({ error: 'Method Not Allowed' });
  }

  try {
    const challenges = createChallenge(5, 4, 60);
    res.status(200).json({ challenges });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate challenge' });
  }
}

import type { NextApiRequest, NextApiResponse } from 'next';
import { verifySolution } from 'ribaunt';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method Not Allowed' });
  }

  const { tokens, solutions } = req.body;

  if (!tokens || !solutions) {
    return res.status(400).json({ success: false, error: 'Missing tokens or solutions' });
  }

  const isValid = await verifySolution(tokens, solutions, {
    onWarning: (warning) => {
      console.log('captcha warning', warning.reason, warning.message);
    },
  });

  if (isValid) {
    return res.status(200).json({ success: true });
  }
  return res.status(400).json({ success: false, error: 'Invalid or expired CAPTCHA solution' });
}

Sunucusuz ve edge dağıtımları

Varsayılan replayPrevention: 'local' modu, kullanılan token ID’lerini süreç içi bir Map içinde saklar. Uygulamanız sunucusuz işlevler olarak veya birden fazla örnek üzerinde çalıştığında, her soğuk başlatma boş bir depo ile başlar, böylece bir örneğe karşı çözülen bir token başka bir örneğe karşı tekrar oynatılabilir.Örnekler arası tekrar oynatmaları önlemek için, atomik bir dağıtık depo tarafından desteklenen bir replayStore adaptörü (örneğin SET NX işlemli Redis) ile birlikte replayPrevention: 'remote' iletin:

const isValid = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: myRedisReplayStore,
});

replayStore, belirli bir jti ilk kez görüldüğünde atomik olarak true ve sonraki herhangi bir çağrıda false döndüren bir consume(jti: string, expiresAt: number): Promise<boolean> yöntemi uygulamalıdır.

​Ortam kurulumu

​App Router (Next.js 13+)

​Pages Router (Next.js 12 ve altı)

​Sunucusuz ve edge dağıtımları

Ortam kurulumu

App Router (Next.js 13+)

Pages Router (Next.js 12 ve altı)

Sunucusuz ve edge dağıtımları