Node.js captcha generator

Usage no npm install needed!

<script type="module">
  import vcaptchaStateless from '';



Build Status Coverage Status Known Vulnerabilities codebeat badge

Simple but user-friendy Node.js stateless captcha generator, based on vCAPTCHA. It makes the user pick up 2 pictures (in sequence) among several (5 by default). Should be enough for low security forms.

WARNING : this stateless version can only be used if captcha requests are somehow limited, for example with nginx or iptables, and the request rate must match the expiresIn parameter you provide. Otherwise, the client will be able to use the same captcha over and over, making it useless. To avoid this, please use the original stateful version of vCAPTCHA.

vCAPTCHA preview

Getting Started

What it does :

  • generate base64 pictures to display in the client;
  • generate a phrase to help you pick up the right pictures;
  • generate pictures names only if you want a custom phrase;
  • generate a key, which is simply the encoded solution.

All this data must be passed to the client. The key must be sent back to the server along with the guessed solution.


npm i --save vcaptcha-stateless



  • Initialize vCaptcha
  • options <Object>
    • secret Required: JWT secret
    • maxFails Default: 10 - max fails allowed per userId

create(options, callback)

  • options <Object>
    • userId Default: ''
    • expiresIn Default: 60 - seconds
    • language Default: 'en' - also supported: 'fr'
    • length Default: 5 - number of pictures to send to the client
    • failCount Default: 0 - current fail count - set automatically
  • returns { key, data, names, phrase }
    • captcha <Object>
      • key JWT token containing the captcha data
      • data base64 pictures array
      • phrase explanation to solve the captcha
      • names pictures to find to solve the captcha, to create your own phrase
    • count fail count

solve(options, callback)

  • options <Object>
    • key Required: key of the captcha to solve
    • solution Required: guessed solution provided by the client.
  • callback <Function> returns (valid, newCaptcha)
    • valid <Boolean> whether or not captcha is solved
    • newCaptcha <Object> if validation failed.


Try it on RunKit.

const vCaptcha = require('vcaptcha-stateless')({ 
  secret: 'secret'

const captcha = vCaptcha.create();

  key: captcha.key,
  solution: captcha.solution
}, (valid, newCaptcha) => {
  // if (valid) newCaptcha = undefined

Client use

Example with Angular template.

<div class="captcha">
  <h5 *ngIf="error">Too many fails, come back later.</h5>
  <div *ngIf="!error" class="captcha-box">
    <label><span>{{ captcha.phrase }}</span></label>
    <ul class="thumbnails selector">
      <li *ngFor="let src of; let i = index">
        <div class="thumbnail" [class.selected]="isSelected(i)" (click)="toggleSelect(i)">
          <img class="image" [src]="'data:image/png;base64,'+ src">


Pictures are taken from deprecated VisualCaptcha.