Zum Hauptinhalt springen
Ribaunt liefert TypeScript-Typen für alle seine öffentlichen APIs aus. Importiere Typen aus ribaunt zur Verwendung in deinem serverseitigen Code.

​
ChallengeToken

Ein signiertes JWT-Challenge-Token. Dies ist der Zeichenkettenwert, der im Array von createChallenge() zurückgegeben wird, und der Wert, den du an verifySolution() zurückgibst. 
type ChallengeToken = string; // A signed JWT challenge token

​
ChallengeSolution

Die vom Browser-Solver (oder von solveChallenge() in Tests) erzeugte Proof-of-Work-Lösung. Der nonce ist der Wert, der, wenn er mit der Challenge-Zeichenkette gehasht wird, einen SHA-256-Digest erzeugt, der mit der erforderlichen Anzahl führender Null-Hexziffern beginnt. 
interface ChallengeSolution {
  nonce: string; // The nonce that satisfies the PoW condition
  hash: string;  // The SHA-256 hash (hex) produced by nonce
}

​
ReplayStore

Die Schnittstelle, die du implementierst, um verteilten Replay-Schutz bereitzustellen, wenn replayPrevention auf 'remote' gesetzt ist. Du übergibst deine Implementierung über options.replayStore an verifySolution(). 
interface ReplayStore {
  consume(jti: string, expiresAt: number): Promise<boolean>;
}
jti ist die JWT-Token-ID, die die Challenge eindeutig identifiziert. expiresAt ist ein Unix-Zeitstempel in Sekunden, der angibt, wann das Token abläuft. Gib true zurück, um die Einreichung zuzulassen (erste Verwendung), und false, um sie abzulehnen (Replay erkannt). Deine Implementierung muss atomar sein — verwende eine Primitive wie Redis SET NX EXAT, um Race Conditions zu vermeiden.

​
LocalReplayStore

Die eingebaute, prozesslokale Implementierung von ReplayStore, exportiert aus ribaunt. Sie speichert verbrauchte Token-IDs im Speicher und entfernt Einträge automatisch, sobald deren TTL abgelaufen ist. Verwende sie, wenn replayPrevention auf 'local' gesetzt ist (Standard) — sie wird in diesem Modus automatisch verwendet. Du kannst sie auch direkt instanziieren, wenn du einen dedizierten Per-Handler-Store benötigst. 
class LocalReplayStore implements ReplayStore {
  async consume(jti: string, expiresAt: number): Promise<boolean>;
}

import { LocalReplayStore } from 'ribaunt';

const store = new LocalReplayStore();

const valid = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: store,
});
LocalReplayStore ist nicht für Multi-Prozess- oder Serverless-Deployments geeignet. Implementiere für diese Umgebungen deinen eigenen ReplayStore, der von einem verteilten, atomaren Store wie Redis SET NX EXAT gestützt wird.

​
ReplayPreventionMode

Steuert, wie verifySolution() verhindert, dass ein Token mehr als einmal eingereicht wird. 
type ReplayPreventionMode = 'disabled' | 'local' | 'remote';
  • 'local' (Standard) — Replay-Prüfungen erfolgen prozesslokal. Geeignet für Single-Prozess-Deployments.
  • 'remote' — Replay-Prüfungen verwenden deinen ReplayStore. Verwende dies für Serverless- oder horizontal skalierte Deployments.
  • 'disabled' — keine Replay-Prüfungen. Tokens können wiederverwendet werden, bis sie ablaufen. Verwende dies nur, wenn eine andere Schicht den Replay-Schutz übernimmt.

​
VerifySolutionOptions

Optionale Konfiguration, die als drittes Argument an verifySolution() übergeben wird. 
interface VerifySolutionOptions {
  replayPrevention?: ReplayPreventionMode; // default: 'local'
  replayStore?: ReplayStore;               // required when replayPrevention is 'remote'
  debug?: boolean;                          // default: true in development
  onWarning?: (warning: VerifyWarning) => void;
}

​
VerifyWarning

Das strukturierte Warn-Objekt, das an den onWarning-Callback übergeben wird, wenn verifySolution() ein Problem feststellt. Ermöglicht das Erfassen von Telemetrie, ohne die Konsolenausgabe zu aktivieren. 
interface VerifyWarning {
  reason: VerifyWarningReason;
  message: string;
  error?: unknown;
}

​
VerifyWarningReason

Eine String-Union, die die Kategorie des Verifizierungsfehlers beschreibt. Du kannst sie verwenden, um Warnungen an verschiedene Monitoring-Kanäle oder Metriken weiterzuleiten. 
type VerifyWarningReason =
  | 'invalid-token'
  | 'expired-token'
  | 'invalid-solution'
  | 'replay-detected'
  | 'configuration-error';

​
SolveChallengeOptions

Optionale Sicherungen, die an solveChallenge() übergeben werden, um zu verhindern, dass es während Tests unbegrenzt läuft. 
interface SolveChallengeOptions {
  maxIterations?: number; // hard cap on nonce attempts
  maxDurationMs?: number; // default: 30000 ms
}

​
WidgetState

Importiert aus ribaunt/widget. Stellt den aktuellen Zustand des CAPTCHA-Widgets im Browser dar. 
type WidgetState = 'initial' | 'verifying' | 'done' | 'error';

​
RibauntWidgetHandle

Importiert aus ribaunt/widget-react. Dies ist der imperative Handle, der über eine React-ref bereitgestellt wird, die an die <RibauntWidget>-Komponente angehängt ist. Verwende ihn, um das Widget programmatisch aus deinem Anwendungscode heraus zu steuern. 
interface RibauntWidgetHandle {
  reset(): void;
  getState(): WidgetState | undefined;
  startVerification(): void;
}