Documentation

npm install imrobot

const widget = document.querySelector('imrobot-widget')

widget.getChallenge()            // Returns the current Challenge object
widget.submitAnswer(answer)      // Submit a computed answer
widget.reset()                   // Generate a new challenge

import {
  generateChallenge,
  solveChallenge,
  verifyAnswer,
  createToken,
} from 'imrobot/core'

// 1. Generate a challenge
const challenge = generateChallenge({ difficulty: 'medium' })

// 2. Solve (what an AI agent does)
const answer = solveChallenge(challenge)

// 3. Verify
const isValid = verifyAnswer(challenge, answer) // true

// 4. Create a verification token
const token = createToken(challenge, answer, startTime)

const challenge = await verifier.generate()
// { ...challenge, hmac: '64-char-hex', expiresAt: 1711234567890 }

// Override per-request:
const hard = await verifier.generate({ difficulty: 'hard', ttl: 10_000 })

const result = await verifier.verify(challenge, answer)

// VerifyResult {
//   valid: boolean
//   reason?: 'expired' | 'invalid_hmac' | 'wrong_answer' | 'tampered'
//   elapsed?: number      // ms since challenge creation
//   suspicious?: boolean  // true if elapsed > 5s
// }

import express from 'express'
import { requireAgent, createAgentRouter } from 'imrobot/server'

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

// Mount challenge/verify endpoints
const router = createAgentRouter({
  secret: process.env.IMROBOT_SECRET!,
  difficulty: 'medium',
  tokenTTL: 300_000, // 5 min token lifetime
})
app.post('/imrobot/challenge', router.challenge)
app.post('/imrobot/verify', router.verify)

// Protect your API with the middleware
const agentOnly = requireAgent({
  secret: process.env.IMROBOT_SECRET!,
  rateLimit: { windowMs: 60_000, maxRequests: 30 },
})
app.get('/api/data', agentOnly, (req, res) => {
  res.json({ message: 'Only verified agents reach here' })
})

import { createTokenIssuer } from 'imrobot/server'

const issuer = createTokenIssuer({
  secret: process.env.IMROBOT_SECRET!,
  issuer: 'my-app',
  tokenTTL: 300_000, // 5 minutes
})

// Issue a token after successful challenge verification
const token = await issuer.issue({
  challengeId: challenge.id,
  difficulty: 'medium',
  solveTimeMs: 42,
  suspicious: false,
})

// Verify a token from the X-Agent-Proof header
const result = await issuer.verify(token)
// { valid: true, payload: { iss, sub, iat, exp, imr: { ... } } }

// Decode without verification (for inspection)
const payload = ProofTokenIssuer.decode(token)

import { invisibleVerify } from 'imrobot/core'

const result = await invisibleVerify({
  challengeUrl: 'https://api.example.com/imrobot/challenge',
  verifyUrl: 'https://api.example.com/imrobot/verify',
  agentId: 'my-bot-v1',
  maxRetries: 3,
  timeout: 10_000,
})

if (result.success) {
  console.log('Verified!', result.proofToken)
  console.log(`Solved in ${result.solveTime}ms, ${result.attempts} attempt(s)`)

  // Use the proof token for subsequent API calls
  fetch('/api/protected', {
    headers: { 'X-Agent-Proof': result.proofToken },
  })
} else {
  console.error('Failed:', result.error)
}

# Generate a challenge
npx imrobot challenge --difficulty hard

# Solve a challenge (pipe from generate)
npx imrobot challenge | npx imrobot solve

# Run a performance benchmark
npx imrobot benchmark --iterations 1000 --difficulty medium

# Show library info
npx imrobot info

import { createDiscoveryHandler } from 'imrobot/server'

const discovery = createDiscoveryHandler({
  challengePath: '/imrobot',
  name: 'My Agent API',
  description: 'Agent-verified data service',
})

app.get('/.well-known/imrobot.json', discovery)

import { buildDiscoveryDocument } from 'imrobot/server'

const doc = buildDiscoveryDocument({
  challengePath: '/imrobot',
  name: 'My Agent API',
})
// Serve `doc` as JSON at /.well-known/imrobot.json

{
  "protocol": "imrobot",
  "version": "1.0",
  "name": "My Agent API",
  "description": "Agent-verified data service",
  "endpoints": {
    "challenge": "/imrobot/challenge",
    "verify": "/imrobot/verify",
    "proofHeader": "X-Agent-Proof"
  },
  "difficulties": ["easy", "medium", "hard"],
  "instructions": "1. GET the challenge endpoint..."
}

import { RateLimiter } from 'imrobot/server'

const limiter = new RateLimiter({
  windowMs: 60_000,    // 1-minute sliding window
  maxRequests: 30,     // max 30 requests per window
  onLimitReached: (key) => console.warn(`Rate limited: ${key}`),
})

// Check if a request is allowed
if (!limiter.isAllowed(clientIp)) {
  // 429 Too Many Requests
}

// Inspect current status
const status = limiter.getStatus(clientIp)
// { remaining: 7, resetAt: 1711540860000 }

// Reset a specific key or all keys
limiter.reset(clientIp)
limiter.reset() // clear all

// Clean shutdown
limiter.destroy()

import type {
  Challenge,              // Base challenge object
  SignedChallenge,        // Challenge + HMAC signature
  Operation,              // Discriminated union of 27 operations
  Difficulty,             // 'easy' | 'medium' | 'hard'
  ImRobotToken,           // Client verification token
  ImRobotConfig,          // Client widget configuration
  ServerConfig,           // Server verifier configuration
  VerifyResult,           // Server verification result
  AgentProofToken,        // JWT-like proof-of-agent token payload
  SerializedProofToken,   // Encoded token string
  InvisibleVerifyResult,  // Result from invisible verification
} from 'imrobot'

// Or import from specific entry points:
import type { SignedChallenge, VerifyResult } from 'imrobot/server'
import type { Challenge, Operation } from 'imrobot/core'
import { invisibleVerify, AdaptiveDifficulty, ImageChallengePool } from 'imrobot/core'
import { ProofTokenIssuer, requireAgent, createAgentRouter } from 'imrobot/server'

import { AdaptiveDifficulty } from 'imrobot/core'

const adaptive = new AdaptiveDifficulty({
  initialDifficulty: 'medium',
  escalateAfterFailures: 2,   // escalate after 2 consecutive failures
  relaxAfterSuccesses: 5,     // relax after 5 consecutive successes
})

// Record outcomes as agents solve challenges
adaptive.recordAttempt('agent_123', { success: true, solveTimeMs: 42 })

// Get recommended difficulty
const diff = adaptive.getDifficulty('agent_123')

// Get risk assessment (0-1 score with breakdown)
const risk = adaptive.getRiskAssessment('agent_123')
// { score: 0.15, level: 'low', factors: { failureRate, abnormalTiming, rapidAttempts, inconsistentTiming } }

import { ImageChallengePool } from 'imrobot/core'

const pool = new ImageChallengePool({
  provider: {
    type: 'static',
    images: [
      { imageUrl: '/img/kitchen.png', type: 'object_count',
        question: 'How many red apples?', answer: '3' },
    ],
  },
})

await pool.initialize()
const challenge = pool.getChallenge()
const correct = pool.verifyAnswer(challenge.id, userAnswer)

const pool = new ImageChallengePool({
  provider: {
    type: 'custom',
    generate: async (prompt) => {
      const result = await myAIGenerator(prompt)
      return { imageUrl: result.url }
    },
  },
  poolSize: 100,
  challengeTypes: ['object_count', 'spatial_reasoning'],
  rotationIntervalMs: 3_600_000, // rotate pool every hour
})