Prerequisites
- Node.js 22 or later
expressandribauntinstalled in your project- A
RIBAUNT_SECRETenvironment variable set to a strong random string
Best practices
- Rate limit the challenge endpoint. Use
express-rate-limitto cap how many challenges a single IP can request per minute. Without this, an attacker can farm tokens for offline brute-forcing. You can also plug a limiter directly into Ribaunt by passing arateLimitertocreateChallenge()andverifySolution()— when itscheck()resolvesfalse, Ribaunt throws aRateLimitedError(code: 'rate-limited') that you catch and return as a 429. - Link verification to a session. After a successful
verifySolution()call, return a signed JWT or set an HTTP-only cookie. Require that token on your protected form submission endpoint so you know the CAPTCHA was solved by the same user making the downstream request. - Validate inputs before calling
createChallenge(). Ifdifficulty,amount, orttlSecondscome from config or request data, check that they are positive finite integers first — invalid values throw. - Use
replayPrevention: 'remote'for multi-instance or serverless deployments. The default'local'store is per-process, so it cannot detect replays across separate Node.js processes. Pass a distributed store adapter (e.g. backed by Redis) and setreplayPrevention: 'remote'in yourverifySolution()options. - Bind challenge context when needed. Use
contextincreateChallenge()andverifySolution()when you want the same token to be valid only for a specific flow, such as a signup form or password reset request. - Use
onWarningfor telemetry. TheonWarningcallback receives a structuredVerifyWarningobject with a typedreason('invalid-token','expired-token','replay-detected', etc.) and a human-readablemessage. Wire it to your observability pipeline without enabling verbose debug logs in production. - Emit lifecycle events with
onEvent. PassonEventtocreateChallenge()andverifySolution()to receivechallenge-issued,verify-success, andverify-failureevents.verify-failurereuses theVerifyFailureReasonunion, so you can label metrics or logs by reason.