verifySolution

verifySolution() is called server-side in your verify endpoint to check that the browser correctly solved all challenge tokens. It validates the JWT signature, token expiry, the hash proof, replay state, and optional context binding. Each token carries its own algorithm, so verifySolution() verifies SHA-256 and Argon2id proofs automatically with no extra options.

Import

import { verifySolution } from 'ribaunt';

Signature

function verifySolution(
  token: ChallengeToken | ChallengeToken[],
  nonce: number | string | Array<number | string> | ChallengeSolution | ChallengeSolution[],
  options?: VerifySolutionOptions
): Promise<VerifySolutionResult>

Parameters

ChallengeToken | ChallengeToken[]

required

The original JWT token(s) returned by createChallenge(). Pass the same tokens your challenge endpoint issued.

required

The solution(s) submitted by the browser. Can be:

A single nonce string
An array of nonce strings
A ChallengeSolution object { nonce: string; hash: string }
An array of ChallengeSolution objects (what the widget sends as solutions)

VerifySolutionOptions

Optional configuration object. See the options table below.

Options

Option	Type	Default	Description
`replayPrevention`	`'local' \| 'remote' \| 'disabled'`	`'local'`	Controls how token reuse is prevented
`replayStore`	`ReplayStore`	`undefined`	Required when `replayPrevention` is `'remote'`
`context`	`string`	`undefined`	Requires the same context value that was used when the challenge was issued
`debug`	`boolean`	auto (true in development)	Logs verification warnings to the console
`onWarning`	`(warning: VerifyWarning) => void`	`undefined`	Callback for structured warning events
`rateLimiter`	`RateLimiter`	`undefined`	Bring-your-own rate limiter. When `check()` resolves `false`, `verifySolution()` throws a `RateLimitedError` instead of running verification.
`onEvent`	`(event: RibauntEvent) => void`	`undefined`	Telemetry hook. Emits `verify-success` on pass and `verify-failure` (with the same `reason` as `VerifyFailureReason`) on failure.

Return value

Promise<VerifySolutionResult>. The function returns either:

{ valid: true }

{ valid: false, reason, message }

Examples

Basic usage:

const { tokens, solutions } = req.body;
const result = await verifySolution(tokens, solutions);

if (!result.valid) {
  return res.status(400).json({ success: false, error: result.reason });
}

With structured warning telemetry:

const result = await verifySolution(tokens, solutions, {
  context: 'signup',
  onWarning: (warning) => {
    // warning.reason: 'invalid-token' | 'expired-token' | 'invalid-solution' | 'context-mismatch'
    //                 | 'replay-detected' | 'replay-store-unavailable' | 'configuration-error'
    console.log('captcha warning', warning.reason, warning.message);
  },
});

With a rate limiter and telemetry:

import { verifySolution, RateLimitedError } from 'ribaunt';

try {
  const result = await verifySolution(tokens, solutions, {
    rateLimiter: {
      check: async () => allowRequest(req.ip),
    },
    onEvent: (event) => {
      if (event.type === 'verify-success') metrics.increment('captcha.pass');
      if (event.type === 'verify-failure') {
        metrics.increment('captcha.fail', { reason: event.reason });
      }
    },
  });

  if (!result.valid) {
    return res.status(400).json({ error: result.reason });
  }
} catch (error) {
  if (error instanceof RateLimitedError) {
    return res.status(429).json({ error: error.message });
  }
  throw error;
}

rateLimiter runs before token validation, so it protects the verify endpoint even when callers submit malformed input. onEvent fires only after verification completes; if rateLimiter rejects a request, no event is emitted.

Do not pass context: req.ip just to key the rate limiter. Close over the request instead, as shown above. When you pass context, the tokens must have been created with the identical context value or verification fails with context-mismatch.

With a remote replay store:

const result = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: {
    consume: async (jti, expiresAt) => {
      // Atomic set-if-not-exists with TTL (e.g. Redis SET NX EXAT)
      return await redis.set(jti, '1', 'NX', 'EXAT', expiresAt) !== null;
    },
  },
});

Warning reasons

Reason	Description
`invalid-token`	JWT signature is invalid, the payload is malformed, or the token carries an unknown construction version (`v`)
`expired-token`	Challenge TTL has passed
`invalid-solution`	The nonce does not produce a valid hash
`context-mismatch`	The supplied context does not match the token’s bound context
`replay-detected`	Token was already consumed
`replay-store-unavailable`	The replay store threw during consumption (for example, Redis is unreachable). Verification fails closed.
`configuration-error`	`replayPrevention` is `'remote'` but no `replayStore` was provided

Server API

Types

Import

Signature

Parameters

Options

Return value

Examples

Warning reasons

​Import

​Signature

​Parameters

​Options

​Return value

​Examples

​Warning reasons

Import

Signature

Parameters

Options

Return value

Examples

Warning reasons