als-captcha
v2.1.0
Published
Advanced CAPTCHA library
Downloads
36
Maintainers
alexsorkinReadme
als-captcha
als-captcha is a Node.js library for generating and validating a simple yet effective captcha. It employs a combination of image recognition with noise and tilt, basic math problem solving, and several other strategies to differentiate between human users and bots.
Installation
To install als-captcha, use npm:
npm i als-captchaBasic Usage
const Captcha = require('als-captcha');
const captcha = new Captcha() // dafult params and eng language for audio
// create captcha
app.get('/captcha', async (req, res) => {
const captchaHtml = await captcha.create(req,res,true) // last parameter include audio
res.send(`<!DOCTYPE html>
<html lang="en">
<head>
<title>HEllo</title>
</head>
<body>
<form>
${captchaHtml}
</form>
<body>
</html>
`);
});
// validate captcha
app.post('/submit-captcha', (req, res) => {
if (catpcha.valid(req)) res.send("right");
else res.send("wrong");
});Security Strategies
als-captcha uses multiple strategies to enhance security:
- Image Recognition Challenge: A captcha image with noise, tilt, and bot-unfriendly font.
- Math Problem Solving: A basic math problem that must be solved correctly, ensuring complete text recognition.
- Hidden
importantInfoField: Remains empty and is used to detect bots that might fill it. - Bot Detection through
onchangeEvent: If theonchangeevent does not trigger, thebotfield retains its default value, indicating a bot. - Timestamp and Screen Dimension Check: Captures the time taken to complete the captcha and multiplies the screen's color depth with its width to generate a unique number, which helps in bot detection.
Advanced Usage
Configuration includes 3 parts:
params(Object) - the parameters for captcha class- first parameter in constructor
lang(String) - the language for audio- second parameter in constructor
- default
'eng', available:eng,ru,he
cookieOptions(Object) - options for cookie- available as instance.cookieOptions
prefix(String): Optional. A prefix for cookie names with encrypted values. Default is 's:'.cryptOptions(Object): Optional. An object for initiating encryption.- defaults are: {algorithm: 'aes-256-cbc',ivLength: 16,secretFilePath: './secret'}
- You can provide any of keys, the other will be replaced with defaults more information for encryption on als-crypt
- defaults are: {algorithm: 'aes-256-cbc',ivLength: 16,secretFilePath: './secret'}
Parameters
The parameters includes:
logger(Function): function for logging errors. Defaultconsole.logmaxAge(Number): captcha life time (after this time, captcha outdated). Default is 10 minutesfilePath(String): The place for saving captcha tokens start. Defaultjoin(__dirname, 'captcha-start')
Example for custom cofiguration:
const logs = []
const captcha = new Captcha({
logger:(...e) => logs.push(e),
maxAge:1000*60*30,
filePath:'./captcha-start'
})Language - lang
The Captcha class using als-math-audio-composer for composing audio for captcha.
By default the language is english (eng).
At the moment, available languages are:
eng- englishru- russianhe- hebrew
als-math-audio-composer using sync method to read the files and than caching it.
You can cache all needed sounds on init like this:
const captcha = new Captcha({},'ru') // Set Russian as the captcha language
captcha.audioComposer.cacheAll() // Optionally pre-cache all audio files for faster responseCookie settings
The Captcha using crypted cookies for storing token and captcha result. By default cookies sent with the folowing options:
{
path: '/',
secure: true,
httpOnly: true,
maxAge:60*10,
sameSite:'lax'
}The configuraton builded with als-cookie-options and you can change it.
Here is the example how to change:
const captcha = new Captcha()
captcha.cookieOptions.sameSite = 'strict'