Dot Matrix CAPTCHA

A lightweight, anti-OCR dot-matrix CAPTCHA system designed to prevent automated bot recognition through distorted text rendering. Developed by the system_mini member of EndlessPixel Studio.

Overview

This project implements a server-side CAPTCHA system that generates dot-matrix style verification codes with random distortions to resist OCR-based attacks. It provides both the image generation frontend and verification backend.

Features

• Dot Matrix Characters: Uses a custom 5x3 dot matrix pattern for alphanumeric characters
• Anti-OCR Protection: Random rotation, noise dots, and positional jitter
• Server-Side Validation: Secure token-based verification system
• Simple API: RESTful endpoints for verification and status checks
• Lightweight: Minimal dependencies, easy to deploy

Installation

1. Clone the repository:

# use Git to clone the repository
git clone https://github.com/EndlessPixel/captcha.git
# or use GitHub CLI
gh repo clone EndlessPixel/captcha
# change directory to the project folder
cd captcha

2. Start the server:

# start the server
node server.js

The server will run on port 3000 by default.

API Endpoints

Standard Endpoints

1. Get CAPTCHA

• Endpoint: GET /get-captcha
• Response: SVG format CAPTCHA image

2. CAPTCHA Verification

• Endpoint: POST /verify
• Content-Type: application/x-www-form-urlencoded
• Parameters:
  • userCode: User-input CAPTCHA code
• Success Response:

{
  "success": true,
  "message": "Verification successful",
  "uid": "xxxx-xxxx-xxxx-xxxx-xxxx"
}

• Error Response:

{
  "success": false,
  "message": "Verification code error"
}

3. Verification Status Check

• Endpoint: GET /inquire?uid={verification_uid}
• Parameters:
  • uid: Verification UID received from /verify endpoint
• Response: Returns true if verified, false if not

API Version Endpoints

1. Get CAPTCHA (API)

• Endpoint: GET /api/captcha
• Response: JSON format with token and base64-encoded CAPTCHA image

{
  "success": true,
  "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "captcha": "data:image/svg+xml;base64,..."
}

2. CAPTCHA Verification (API)

• Endpoint: POST /api/verify
• Content-Type: application/x-www-form-urlencoded
• Parameters:
  • userCode: User-input CAPTCHA code
  • token: Token received from /api/captcha endpoint
• Success Response:

{
  "success": true,
  "message": "Verification successful",
  "uid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

3. Verification Status Check (API)

• Endpoint: GET /api/inquire?uid={verification_uid}
• Parameters:
  • uid: Verification UID received from /api/verify endpoint
• Response:

{
  "success": true,
  "verified": true
}

Integration Guide

Method 1: Direct Web Interface

Visit http://localhost:3000 to use the web-based CAPTCHA system.

Method 2: JavaScript SDK

Basic Usage

<!-- Add a div container in your page -->
<div id="captcha-container"></div>

<!-- Include the CAPTCHA SDK -->
<script src="/captcha-sdk.js"></script>

Advanced Usage

// Custom configuration
window.initCaptcha({
    containerId: 'custom-captcha', // Custom container ID
    onSuccess: function(uid) {
        console.log('Verification successful, UID:', uid);
        // Handle successful verification
    },
    onError: function(message) {
        console.log('Verification failed:', message);
        // Handle verification failure
    },
    onExpire: function() {
        console.log('CAPTCHA expired');
        // Handle expired CAPTCHA
    }
});

Method 3: API Integration

Get CAPTCHA

const response = await fetch('/api/captcha', {
    method: 'GET'
});
const result = await response.json();
// Use result.token and result.captcha

Verify CAPTCHA

const response = await fetch('/api/verify', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
        userCode: 'ABCD',
        token: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    })
});
const result = await response.json();
// Use result.uid for status checks

Check Verification Status

const response = await fetch('/api/inquire?uid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', {
    method: 'GET'
});
const result = await response.json();
// Check result.verified

Configuration

Modify server.js to change:

• Server port (default: 3000)
• Verification token storage and expiration
• CAPTCHA character set

Security Considerations

• Server-side validation prevents client-side tampering
• Verification tokens are randomly generated and stored
• Implement rate limiting in production environments

Browser Support

• Chrome: 60+
• Firefox: 55+
• Safari: 11+
• Edge: 79+

Project Structure

captcha/            # Dot Matrix CAPTCHA project folder
├─┬── docs/         # Documentation and examples
│ ├── api.html      # API usage example
│ └── sdk-demo.html # SDK usage example
├──── index.html    # Main HTML file
├──── server.js     # Node.js server
├─┬── public/       # Public assets
│ ├── style.css     # Stylesheet
│ ├── script.js     # Frontend logic
│ └── captcha-sdk.js # CAPTCHA SDK
├──── LICENSE       # MIT License
└──── README.md     # This file

License

MIT License © 2024-2026 EndlessPixel Studio

Contact

• Project URL: https://github.com/EndlessPixel/captcha?target=https://github.com
• Developer: system_mini (EndlessPixel Studio)