xauth-captcha

A lightweight, robust, and dependency-minimal CAPTCHA generation library for Rust. Originally designed for the xauth-ecosystem, it provides an easy-to-use Builder API, built-in obfuscation, and a dynamic character grid based on the original PHP algorithm by tarunk04/Captcha_Generator.

Features

• Dynamic Grid Layout: Automatically computes the optimal row/column arrangement for any character count by evaluating cell sizes against the image dimensions, maximizing font size while keeping characters bot-resistant.
• Built-in Fonts: Bundles 10 unique TrueType fonts. Each character is rendered using a randomly selected font from the pool.
• Lightweight Noise Generation: Employs a custom, zero-dependency Bresenham's line algorithm to render obfuscation lines and random dots without pulling in heavy external image processing crates.
• Random Code Generation: Secure text generation using a strictly safe character set (ABCDEFGHJKLMNPQRSTUVWXYZ23456789) to prevent ambiguous characters like 0 vs O or 1 vs I.
• Fluent API: Highly configurable CaptchaBuilder for seamless integration, deserializable from CaptchaConfig (TOML/JSON/YAML via serde).

Usage

use xauth_captcha::{CaptchaBuilder, CaptchaConfig};

fn main() {
    // You can use the Builder directly
    let (text, image) = CaptchaBuilder::new()
        .width(256)
        .height(80)
        .length(6)
        .build();
    
    // OR initialize from a serde config
    let config = CaptchaConfig::default();
    let (text_from_config, image_from_config) = CaptchaBuilder::from_config(&config).build();

    image.save("captcha_output.png").unwrap();
    println!("Generated CAPTCHA: {}", text);
}

Configuration

If you are using xauth-captcha as a library in your application, you can deserialize configuration directly from TOML, JSON, or YAML into CaptchaConfig using serde.

Here is a reference of the available fields:

Field	Type	Default	Description
width	u32	128	The total width of the generated image.
height	u32	128	The total height of the generated image.
length	usize	5	The number of characters to generate.
charset	Option<String>	None	Custom character set to use. Defaults to a safe alphabet without ambiguous characters.
noise_dots	Option<usize>	None (65)	Number of random RGB dots scattered across the image.
noise_lines	Option<usize>	None (30)	Number of random Bresenham lines drawn across the image.
enable_wave	bool	false	Whether to apply a sine-wave distortion to the final image.

Running the Example

You can run the included example to generate a sample CAPTCHA image directly:

cargo run --example simple

Check the root directory for the resulting captcha_output.png file!

Contributing

Contributions are welcome and appreciated! Here's how you can contribute:

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This library is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2). Please note that this is a custom license. See the LICENSE file for details.