CaptchaLM

The reverse CAPTCHA for the AI age
Let AI agents through. Keep humans guessing.

Installation • Quick Start • API Docs • Challenge Types

What is CaptchaLM?

Traditional CAPTCHAs block bots and let humans through. CaptchaLM flips the script.

It presents computational challenges that are trivial for AI agents but tedious for humans:

AI Agents	Humans
✅ Execute code instantly	❌ Mental math is slow
✅ Decode base64/hex easily	❌ Manual decoding is painful
✅ Parse structured data	❌ Pattern matching takes time
✅ Chain operations precisely	❌ Easy to make mistakes

Use cases:

API endpoints that should only be accessed by AI agents
Rate limiting humans while allowing automated workflows
Creating "AI-only" zones in your application

Installation

npm install captchalm

Quick Start

1. Protect your server

import express from 'express';
import { createExpressMiddleware } from 'captchalm';

const app = express();
app.use(express.json());

const { protect, challenge } = createExpressMiddleware({
  secret: process.env.UNCAPTCHA_SECRET,
  difficulty: 'medium', // 'easy' | 'medium' | 'hard'
});

// Endpoint where agents get challenges
app.get('/challenge', challenge);

// Protected endpoint - only AI agents can access
app.post('/api/agent-only', protect, (req, res) => {
  res.json({ message: 'Welcome, AI agent!' });
});

app.listen(3000);

2. Access from your AI agent

import { CaptchaLMSolver } from 'captchalm/client';

const solver = new CaptchaLMSolver();

// One-liner to solve and access protected endpoint
const response = await solver.completeProtectedRequest(
  'https://api.example.com/challenge',
  'https://api.example.com/api/agent-only',
  { method: 'POST', body: JSON.stringify({ data: 'hello' }) }
);

console.log(await response.json());
// { message: 'Welcome, AI agent!' }

That's it! Your endpoint is now AI-agent-only.

How It Works

Agent requests a challenge from your /challenge endpoint
Server generates a computational task (math, code execution, decoding, etc.)
Agent solves the challenge using the solver SDK
Agent sends solution with the protected request
Server verifies and grants access if correct

┌─────────────┐     GET /challenge      ┌─────────────┐
│   AI Agent  │ ──────────────────────► │   Server    │
│             │ ◄────────────────────── │             │
│             │     Challenge data      │             │
│             │                         │             │
│  [Solver]   │     POST /api/data      │  [Verify]   │
│   solves    │ ──────────────────────► │   checks    │
│             │   + solution headers    │             │
│             │ ◄────────────────────── │             │
└─────────────┘     ✓ Access granted    └─────────────┘

Challenge Types

CaptchaLM includes 5 types of challenges. See docs/challenges.md for details.

Type	What it tests
Function Execution	Run provided code with parameters
Chained Operations	Sequential math operations
Encoded Instructions	Decode and compute (base64, hex, rot13)
Pattern Extraction	Query structured data
Code Transform	Execute and transform results

Configuration

createExpressMiddleware({
  // Required
  secret: 'your-secret-key',
  
  // Optional
  difficulty: 'medium',        // 'easy' | 'medium' | 'hard'
  expirationMs: 30000,         // Challenge timeout (30s default)
  challengeTypes: ['function_execution', 'chained_operations'],
  rateLimit: {
    maxAttempts: 10,           // Per client
    windowMs: 60000,           // 1 minute window
  },
});

Documentation

📖 API Reference - Full API documentation
🧩 Challenge Types - Detailed challenge descriptions
🔒 Security Guide - Security considerations
🤖 For AI Agents - Machine-readable documentation

Security

HMAC-signed challenges prevent tampering
Timing-safe comparison prevents timing attacks
Rate limiting stops brute force attempts
One-time use challenges can't be replayed
Configurable expiration limits attack window

License

MIT

_{🤖 AI agents: see docs/llm.txt for machine-readable documentation}

5.1 KiB Raw Permalink Blame History