Types - Ribaunt

Ribaunt ships TypeScript types for all its public APIs. Import types from ribaunt for use in your server-side code.

`ChallengeToken`

A signed JWT challenge token. This is the string value returned in the array from createChallenge() and the value you pass back to verifySolution().

type ChallengeToken = string; // A signed JWT challenge token

`ChallengeSolution`

The proof-of-work solution produced by the browser solver (or by solveChallenge() in tests). The nonce is the value that, when hashed with the challenge string, produces a SHA-256 digest beginning with the required number of leading zero hex digits.

interface ChallengeSolution {
  nonce: string; // The nonce that satisfies the PoW condition
  hash: string;  // The SHA-256 hash (hex) produced by nonce
}

`ChallengeOptions`

The options object accepted by createChallenge().

interface ChallengeOptions {
  difficulty?: number | 'auto';
  amount?: number;
  ttlSeconds?: number;
  context?: string;
  workload?: Pick<Workload, 'difficulty' | 'amount'>;

  // Only used when difficulty === 'auto':
  targetDurationMs?: number;   // default 750
  riskScore?: number;          // 0–100, default 50
  calibration?: ClientCalibration;
  minDifficulty?: number;      // default 3
  maxDifficulty?: number;      // default 6
  minAmount?: number;          // default 1
  maxAmount?: number;          // default 8
}

`ClientCalibration`

Reported benchmark from the client used as a raise-only signal in "auto" mode.

interface ClientCalibration {
  iterations: number;
  durationMs: number;
}

`Workload` and `AdaptiveWorkloadOptions`

selectWorkload() returns a Workload object and accepts an optional adaptive configuration.

interface AdaptiveWorkloadOptions extends WorkloadBounds {
  riskScore?: number;
  targetDurationMs?: number;
  calibration?: ClientCalibration;
}

interface Workload {
  difficulty: number;
  amount: number;
  estimatedAttempts: number;
}

`ReplayStore`

The interface you implement to provide distributed replay prevention when replayPrevention is set to 'remote'. You pass your implementation to verifySolution() via options.replayStore.

interface ReplayStore {
  consume(jti: string, expiresAt: number): Promise<boolean>;
  consumeMany?(jtis: string[], expiresAt: number): Promise<boolean>;
}

jti is the JWT token ID uniquely identifying the challenge. expiresAt is a Unix timestamp in seconds indicating when the token expires. Return true to allow the submission (first use) and false to reject it (replay detected). Your implementation must be atomic — use a primitive such as Redis SET NX EXAT to avoid race conditions.

`LocalReplayStore`

The built-in, process-local implementation of ReplayStore exported from ribaunt. It stores consumed token IDs in memory and automatically evicts entries once their TTL has passed. Use this when replayPrevention is 'local' (the default) — it is used automatically in that mode. You can also instantiate it directly when you need a dedicated per-handler store.

class LocalReplayStore implements ReplayStore {
  async consume(jti: string, expiresAt: number): Promise<boolean>;
  async consumeMany(jtis: string[], expiresAt: number): Promise<boolean>;
}

import { LocalReplayStore } from 'ribaunt';

const store = new LocalReplayStore();

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

LocalReplayStore is not suitable for multi-process or serverless deployments. For those environments, implement your own ReplayStore backed by a distributed atomic store such as Redis SET NX EXAT.

`ReplayPreventionMode`

Controls how verifySolution() prevents a token from being submitted more than once.

type ReplayPreventionMode = 'disabled' | 'local' | 'remote';

'local' (default) — replay checks are process-local. Suitable for single-process deployments.
'remote' — replay checks use your ReplayStore. Use this for serverless or horizontally scaled deployments.
'disabled' — no replay checks. Tokens can be reused until they expire. Only use this if another layer handles replay prevention.

`VerifySolutionOptions`

Optional configuration passed as the third argument to verifySolution().

interface VerifySolutionOptions {
  replayPrevention?: ReplayPreventionMode; // default: 'local'
  replayStore?: ReplayStore;               // required when replayPrevention is 'remote'
  context?: string;                        // optional challenge scope
  debug?: boolean;                         // default: true in development
  onWarning?: (warning: VerifyWarning) => void;
}

`VerifySolutionResult`

The structured result returned by verifySolution().

type VerifySolutionResult =
  | { valid: true }
  | { valid: false; reason: VerifyFailureReason; message: string };

`VerifyWarning`

The structured warning object passed to the onWarning callback when verifySolution() encounters a problem. This allows you to capture telemetry without enabling console output.

interface VerifyWarning {
  reason: VerifyWarningReason;
  message: string;
  error?: unknown;
}

`VerifyFailureReason` and `VerifyWarningReason`

A string union describing the category of verification failure. You can use this to route warnings to different monitoring channels or metrics.

type VerifyFailureReason =
  | 'invalid-token'
  | 'expired-token'
  | 'invalid-solution'
  | 'context-mismatch'
  | 'replay-detected'
  | 'configuration-error';

type VerifyWarningReason = VerifyFailureReason;

`SolveChallengeOptions`

Optional guardrails passed to solveChallenge() to prevent it from running indefinitely during tests.

interface SolveChallengeOptions {
  maxIterations?: number; // hard cap on nonce attempts
  maxDurationMs?: number; // default: 30000 ms
}

`WidgetState`

Imported from ribaunt/widget. Represents the current state of the CAPTCHA widget in the browser.

type WidgetState = 'initial' | 'fetching' | 'solving' | 'verifying' | 'done' | 'error';

`WidgetErrorCode`

Machine-readable error classification emitted on the widget’s error event detail.code.

type WidgetErrorCode =
  | 'timeout'
  | 'aborted'
  | 'challenge-fetch-failed'
  | 'invalid-challenge'
  | 'solve-failed'
  | 'verification-failed'
  | 'worker-unavailable'
  | 'unknown';

`RibauntWidgetHandle`

Imported from ribaunt/widget-react. This is the imperative handle exposed via a React ref attached to the <RibauntWidget> component. Use it to programmatically control the widget from your application code.

interface RibauntWidgetHandle {
  reset(): void;
  getState(): WidgetState | '';
  startVerification(): void;
}

​ChallengeToken

​ChallengeSolution

​ChallengeOptions

​ClientCalibration

​Workload and AdaptiveWorkloadOptions

​ReplayStore

​LocalReplayStore

​ReplayPreventionMode

​VerifySolutionOptions

​VerifySolutionResult

​VerifyWarning

​VerifyFailureReason and VerifyWarningReason

​SolveChallengeOptions

​WidgetState

​WidgetErrorCode

​RibauntWidgetHandle