Documentation

Overview

AirCaptcha uses behavioral analysis, browser fingerprinting, and cryptographic challenges to distinguish humans from bots. Unlike traditional captchas, it works silently in the background.

Key Features:

• Zero user friction - no puzzles or challenges
• AES-256-GCM encrypted communication
• Browser fingerprinting (Canvas, WebGL, Audio)
• Behavioral analysis (mouse movement, typing patterns)
• Proof-of-Work challenges for suspicious traffic
• Bot detection (Selenium, Puppeteer, etc.)

Installation

To use AirCaptcha on your website, you'll need:

1. Create an API key pair from your dashboard
2. Include the client-side script with your Site Key (public)
3. Verify tokens on your server using your Secret Key (private)

Key Types:

• ac_site_... - Site Key (public) - Safe to include in frontend code
• ac_secret_... - Secret Key (private) - Keep secure, only use server-side

Quick Start

Here's a minimal example to get started:

<!-- 1. Include the script -->
<script src="https://your-domain.com/api/captcha/script.js"></script>

<!-- 2. Add to your form -->
<form id="my-form">
    <input type="text" name="email" required>
    <button type="submit">Submit</button>
</form>

<script>
// 3. Initialize and use
const captcha = new AirCaptcha({
    apiEndpoint: '/api/captcha',
    siteKey: 'YOUR_SITE_KEY'
});

captcha.on('ready', () => {
    document.getElementById('my-form').onsubmit = async (e) => {
        e.preventDefault();
        const result = await captcha.execute();
        if (result.success) {
            // Send result.token to your server for verification
            submitFormWithToken(result.token);
        }
    };
});

captcha.init();
</script>

Client-Side Setup

The client-side script provides the AirCaptcha class with these options:

const captcha = new AirCaptcha({
    apiEndpoint: '/api/captcha',    // Required: Your captcha API endpoint
    siteKey: 'YOUR_SITE_KEY',       // Required: Your site's API key
    encryptionEnabled: true,        // Enable encrypted communication
    debug: false                    // Enable console logging
});

Available Methods:

• init() - Initialize the captcha (call once on page load)
• execute() - Run verification and get a token
• reset() - Reset the captcha state
• on(event, callback) - Listen for events

Events:

• ready - Captcha initialized and ready
• success - Verification successful
• error - An error occurred

Server-Side Verification

After getting a token from the client, verify it on your server using your Secret Key:

# Python example
import requests

def verify_captcha(token, secret_key):
    """
    token: The token received from the frontend
    secret_key: Your ac_secret_... key (keep this private!)
    """
    response = requests.post(
        'https://your-captcha-server.com/api/captcha/validate-token',
        json={
            'token': token,
            'secret': secret_key  # ac_secret_...
        }
    )
    data = response.json()
    return data.get('valid', False)

// Node.js example
const axios = require('axios');

async function verifyCaptcha(token, secretKey) {
    /**
     * token: The token received from the frontend
     * secretKey: Your ac_secret_... key (keep this private!)
     */
    const response = await axios.post(
        'https://your-captcha-server.com/api/captcha/validate-token',
        {
            token: token,
            secret: secretKey  // ac_secret_...
        }
    );
    return response.data.valid;
}

API Reference

POST /api/captcha/init

Initialize a new captcha challenge.

Request:
{
    "fingerprint": { ... }  // Browser fingerprint data
}

Response:
{
    "success": true,
    "challenge": {
        "challenge_id": "abc123",
        "type": "invisible",
        "expires_at": 1234567890000
    }
}

POST /api/captcha/verify

Verify a challenge solution.

Request:
{
    "challenge_id": "abc123",
    "solution": { ... },
    "fingerprint": { ... },
    "behavior": { ... }
}

Response:
{
    "success": true,
    "token": "eyJ...",
    "score": 0.15,
    "risk_level": "low"
}

POST /api/captcha/validate-token

Validate a token on your server.

Request:
{
    "token": "eyJ..."
}

Response:
{
    "valid": true,
    "payload": {
        "challenge_id": "abc123",
        "score": 0.15,
        "verified_at": 1234567890000
    }
}

Configuration

Server-side configuration options (environment variables):

# Security
CAPTCHA_SECRET=your-secret-key-here
CORS_ORIGINS=https://your-domain.com

# Difficulty
POW_DIFFICULTY=4
POW_MAX_DIFFICULTY=6

# Timing
CHALLENGE_EXPIRY_SECONDS=120
TOKEN_EXPIRY_SECONDS=300

# Rate Limiting
RATE_LIMIT_REQUESTS=30
RATE_LIMIT_WINDOW=60

Security Best Practices

• Always verify tokens server-side - Never trust client-side verification alone
• Use HTTPS - All communication should be encrypted
• Keep your secret key safe - Never expose it in client-side code
• Monitor your traffic - Watch for unusual patterns
• Set appropriate rate limits - Prevent brute force attacks
• Use the risk score - Implement graduated responses based on score

Risk Score Guidelines:

• 0.0 - 0.2 - Very likely human, allow immediately
• 0.2 - 0.4 - Probably human, allow with logging
• 0.4 - 0.6 - Suspicious, consider additional verification
• 0.6 - 0.8 - Likely bot, show fallback challenge or block
• 0.8 - 1.0 - Almost certainly bot, block request

Troubleshooting

Captcha not initializing

Check that:

• The script URL is correct and accessible
• Your site key is valid
• There are no JavaScript errors in the console
• CORS is properly configured on the server

High false positive rate

If legitimate users are being blocked:

• Lower your score threshold
• Check that behavioral data is being collected
• Ensure users have time to interact before verification
• Implement a fallback challenge for borderline cases

Token validation failing

Verify that:

• Tokens are being sent within the expiry window
• Your secret key matches on client and server
• The token hasn't been tampered with
• Client IP hasn't changed between challenge and verification