Sorun giderme - Ribaunt

Hata: "RIBAUNT_SECRET environment variable is not set!"

Neden: RIBAUNT_SECRET ortamınızda eksik veya createChallenge ya da verifySolution’a yapılan ilk çağrıdan önce işleme yüklenmemiş.Düzeltme: Sunucunuz ilk isteğini işlemeden önce değişkenin tanımlandığından emin olun. Bir .env dosyası kullanıyorsanız, dotenv gibi bir araçla giriş noktanızın en üstüne yükleyin:

import 'dotenv/config'; // Must come before any ribaunt imports
import { createChallenge } from 'ribaunt';

Barındırılan çalışma zamanları (Vercel, Railway, Fly.io vb.) için RIBAUNT_SECRET’i kaynak kontrolüne işlemek yerine platformunuzun ortam değişkeni panosu üzerinden ayarlayın. Eğer yanlışlıkla açığa çıkarsa gizli anahtarı hemen değiştirin.

Widget hatası: "Web Crypto API is unavailable. Use HTTPS or localhost."

Neden: Tarayıcı çözücüsü bir güvenli bağlam gerektirir. localhost dışındaki herhangi bir ana bilgisayarda düz HTTP uygun değildir. Bu durum yaygın olarak http://192.168.x.x gibi bir IP adresi üzerinden erişilen yerel ağdaki cihazları etkiler.Düzeltme:

Üretim: uygulamanızı her zaman HTTPS üzerinden sunun.
Geliştirme: makinenizin LAN IP’si yerine http://localhost kullanın. Ağdaki diğer cihazların geliştirme sunucunuza erişmesi gerekiyorsa, mkcert gibi bir araç veya yerel bir ters proxy ile TLS sonlandırın.

verifySolution false döndürüyor — sebep: "expired-token"

Neden: Tarayıcı çözümünü göndermeden önce challenge token’ının TTL’si geçmiştir. Bu, yüklenmesi uzun süren sayfalarda, kullanıcıların göndermeden önce birkaç dakika harcadığı formlarda veya sunucu ile istemci saatleri önemli ölçüde kaymışsa gerçekleşebilir.Düzeltme: Kullanıcılara daha fazla zaman vermek için createChallenge çağrınızda ttlSeconds’ı artırın. Varsayılan 30 saniyedir; karmaşık sayfalar veya formlar için 120–300 değerini düşünün:

// Allow up to 5 minutes to complete the form
const tokens = createChallenge(5, 4, 300);

verifySolution false döndürüyor — sebep: "replay-detected"

Neden: Aynı challenge token’ları birden fazla kez gönderildi. Bu kasıtlıdır — Ribaunt’un varsayılan local yeniden oynatma deposu, token’ları ilk kullanımda tüketilmiş olarak işaretler ve sonraki herhangi bir gönderimi reddeder.Düzeltme: Bu normal kullanıcı akışlarında oluyorsa, büyük olasılıkla ön ucunuzun aynı token’ları yeniden gönderdiği anlamına gelir (örn. form yeniden denemesinde). Yeniden göndermeden önce challenge uç noktanızı tekrar çağırarak her deneme için taze token’lar verin.Bunu sunucusuz veya çoklu örnekli dağıtımlarda görüyorsanız, sorun her işlev çağrısının kendi bellek içi deposuna sahip olmasıdır. Bir örnekte tüketilen token’lar diğerlerine görünmez. Dağıtılmış bir depoyla replayPrevention: 'remote' moduna geçin:

const isValid = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: {
    consume: async (jti, expiresAt) => {
      // Use Redis/Valkey SET NX EX for atomic consume semantics
      const result = await redisClient.set(jti, '1', { NX: true, EXAT: expiresAt });
      return result === 'OK';
    },
  },
});

Widget otomatik olarak doğrulamaya başlamıyor

Neden: auto-verify özniteliği yok veya widget, ayarlanmış olsa bile auto-verify’ın tetiklenmesini engelleyen disabled durumunda.Düzeltme: HTML öğesine auto-verify="true" veya React sarmalayıcısında autoVerify={true} ekleyin:

<ribaunt-widget
  challenge-endpoint="/api/challenge"
  verify-endpoint="/api/verify"
  auto-verify="true"
></ribaunt-widget>

Ayrıca disabled’ın ya yok ya da açıkça "false" olarak ayarlandığından emin olun. Widget devre dışıyken auto-verify tetiklenmeyecektir.

Widget görünmüyor veya yükleme sırasında JS hatası

Neden: Widget betiği doğru yüklenmiyor. Yaygın nedenler arasında derlenmiş dosyaya yanlış bir yol, betiği type="module" olmadan yükleme veya paketin tarayıcı dışa aktarımını doğru çözmeyen bir paketleyici bulunur.Düzeltme: Widget betiğini modül olarak yükleyin ve yolun dist/widget-browser.js’e işaret ettiğini doğrulayın:

<script type="module" src="/node_modules/ribaunt/dist/widget-browser.js"></script>

Widget’ı kendiniz paketliyorsanız, paketleyicinizin Ribaunt paketinden browser dışa aktarım koşulunu çözdüğünden emin olun. Widget tree-shake edilirse veya bulunamazsa, dışa aktarma koşullarını nasıl yapılandıracağınız için çerçevenizin belgelerine bakın.

verifySolution sunucusuz veya edge dağıtımlarında her zaman false döndürüyor

Neden: Varsayılan local yeniden oynatma deposu işlem belleğinde yaşar. Sunucusuz ortamlarda her işlev çağrısı yeni bir işlemdir, bu nedenle bir önceki çağrıda tüketilen token’lar bir sonraki için bilinmez. Bu, bellek içi deponun her gönderimi ilk gibi değerlendirmesine neden olur — ancak iki eşzamanlı çağrı yarışırsa, her ikisi de aynı token’ı tüketebilir veya hiçbiri yeniden oynatmaya karşı koruma sağlamak için durumu yeterince uzun süre tutamaz.Düzeltme: Atomik SET NX EX semantiği kullanan bir Redis veya Valkey bağdaştırıcısı ile replayPrevention: 'remote' moduna geçin:

const isValid = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: {
    consume: async (jti, expiresAt) => {
      const result = await redis.set(`ribaunt:${jti}`, '1', {
        NX: true,
        EXAT: expiresAt,
      });
      return result === 'OK';
    },
  },
});

React sarmalayıcısı Next.js'te bir SSR hatası fırlatıyor

Neden: <ribaunt-widget> web bileşeni, customElements ve window gibi yalnızca tarayıcıya özgü API’ler kullanarak kendini kaydeder. Bunlar sunucu tarafı işleme sırasında mevcut değildir.Düzeltme: RibauntWidget’ı içe aktaran veya işleyen herhangi bir bileşen dosyasının başına 'use client' ekleyin:

'use client';

import { RibauntWidget } from 'ribaunt/widget-react';

Bileşeni next/dynamic ile sarmayın — Ribaunt React sarmalayıcısı, tarayıcı paketinin dinamik içe aktarımını dahili olarak zaten ele alır. İkinci bir dinamik içe aktarma katmanı eklemek bu mekanizmaya müdahale edebilir ve çift yüklemeye veya hidrasyon uyuşmazlıklarına neden olabilir.

​Hata ayıklama günlüklerini etkinleştirme

Hata ayıklama günlüklerini etkinleştirme