captcha-rs

captcha-rs is a library that generate verification images dynamically.

Example pictures are as follows:

Using complexity method

Complexity	Light Mode / Noise Filter	Dark Mode / Noise Filter
Level 1
Level 2
Level 3
Level 4
Level 5
Level 6
Level 7
Level 8
Level 9
Level 10

Using Visual Enhancements and Bot Deterrence

Effect	Image example
Drop Shadow
Heavy Interference
Mild Distortion
Heavy Distortion

Example

Add the following dependency to the Cargo.toml file:

[dependencies]

captcha-rs = { version = "0.5.0", features = ["stateless"] }

And then get started in your main.rs:

use captcha_rs::CaptchaBuilder;

fn main() {
	
	let captcha = CaptchaBuilder::new()
		.length(5)
		.width(130)
		.height(40)
		.dark_mode(false)
		.chars(vec!['A', 'B', 'C', 'D']) // Optional custom characters
		.complexity(1) // min: 1, max: 10
		.compression(40) // min: 1, max: 99
		.drop_shadow(false) // Adds a drop shadow to the text
		.interference_lines(2) // Number of interference lines (min 0)
		.interference_ellipses(2) // Number of distraction circles (min 0)
		.distortion(0) // Level of wavy distortion grid (min 0)
		.build();
	
	println!("text: {}", captcha.text);
	println!("base_img: {}", captcha.to_base64());
	
}

Stateless Verification (Serverless)

With the stateless feature enabled, you can generate a time-bound JWT token that contains a secure hash of the captcha solution. This allows you to verify the user's input on a different server or at a later time without storing the solution in a database or session.

use captcha_rs::{CaptchaBuilder, verify};

fn main() {
    let secret = "your-very-secure-secret";
    
    // 1. Generate captcha and token
    let captcha = CaptchaBuilder::new().length(5).build();
    let (image_base64, token) = captcha.as_tuple(secret, 300).unwrap(); // 5 min expiry
    
    println!("Base64 Image: {}", image_base64);
    println!("Verification Token: {}", token);

    // 2. Later, verify the solution provided by the user
    let user_solution = "abc12"; // This would come from the user's request
    let is_valid = verify(&token, user_solution, secret).unwrap_or(false);
    
    if is_valid {
        println!("Captcha verified successfully!");
    } else {
        println!("Invalid captcha or token expired.");
    }
}

Run

# Dev

💲 cargo run


# Build

💲 cargo build


# Test

💲 cargo test -- --nocapture

Performance

The library is highly optimized for fast image generation. The table below represents benchmarks tested with varying configurations (measured per image):

Note: Benchmarks run on a single thread using cargo bench. Performance will vary based on hardware, but standard generation should easily exceed thousands of images per second.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in captcha-rs by you, shall be licensed as MIT, without any additional terms or conditions.