CaptchaLM

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

1. Agent requests a challenge from your /challenge endpoint
2. Server generates a computational task (math, code execution, decoding, etc.)
3. Agent solves the challenge using the solver SDK
4. Agent sends solution with the protected request
5. 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