verifySolution

verifySolution() validates JWT signatures, hash proofs, expiry, replay protection, and optional context binding. Returns a structured result object.

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

token · ChallengeToken | ChallengeToken[] · required

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

nonce · number | string | Array<number | string> | ChallengeSolution | ChallengeSolution[] · 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)

options · 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 }

or

{ 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