# AGENTS.md - No Human Allowed

> Anti-human verification for AI agents. Proof-of-work captcha that's trivial for agents (~100ms), tedious for humans.

## Quick Start

```bash
npm install nohumanallowed
```

Or use directly with npx (no install needed):
```bash
npx nohumanallowed solve --prefix abc123 --target 0000
```

## Hosted API

Free hosted API at `https://nohumanallowed.com`:

```bash
# Create a challenge
curl https://nohumanallowed.com/api/challenge

# Verify a solution
curl -X POST https://nohumanallowed.com/api/verify \
  -H "Content-Type: application/json" \
  -d '{"prefix":"...","nonce":"...","target":"0000","expiresAt":...,"signature":"..."}'
```

## How It Works

1. **Server creates challenge** with a random prefix and difficulty target
2. **Agent solves challenge** by finding a nonce that produces a SHA-256 hash below the target
3. **Server verifies solution** - stateless, no database needed

The difficulty is tuned so agents solve in ~100ms. Humans would need to write code to solve it—at which point, are they really human?

## Server-Side

```typescript
import { createChallenge, verifyChallenge } from 'nohumanallowed'

// 1. Create a challenge
const challenge = createChallenge({
  difficulty: 4,      // Leading zero hex chars (~100ms solve time)
  expiresIn: 60,      // Seconds until challenge expires
  secret: 'your-secret'  // Optional: for signed challenges
})

// Returns: { prefix, target, expiresAt, signature? }

// 2. Send challenge to agent (via API, webhook, etc.)

// 3. Verify the solution
const result = verifyChallenge({
  prefix: challenge.prefix,
  nonce: submittedNonce,
  target: challenge.target,
  expiresAt: challenge.expiresAt,
  signature: challenge.signature,  // If using signed challenges
  secret: 'your-secret'
})

// Returns: { valid: boolean, error?: string }
```

## Agent-Side

```typescript
import { solveChallenge } from 'nohumanallowed/client'

// Receive challenge from server
const challenge = await fetch('https://api.example.com/challenge')
  .then(r => r.json())

// Solve it (takes ~100ms for difficulty 4)
const solution = solveChallenge({
  prefix: challenge.prefix,
  target: challenge.target,
})

// Returns: { nonce: string, hash: string, iterations: number }

// Submit solution
await fetch('https://api.example.com/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ nonce: solution.nonce })
})
```

## CLI Usage

For agents using shell scripts:

```bash
# Install globally
npm install -g nohumanallowed

# Solve a challenge
nohumanallowed solve --prefix "abc123" --target "0000" 

# Or use the skill script
./solve.sh "prefix" "target"
```

## Difficulty Guide

| Difficulty | Leading Zeros | ~Solve Time | Use Case |
|------------|--------------|-------------|----------|
| 2 | 00 | ~1ms | Testing |
| 3 | 000 | ~15ms | Light verification |
| 4 | 0000 | ~100ms | **Recommended** |
| 5 | 00000 | ~1-2s | High security |
| 6 | 000000 | ~30s | Maximum security |

## Token Generation (Stateless Sessions)

For stateless agent sessions:

```typescript
import { generateToken, verifyToken } from 'nohumanallowed'

// After successful challenge verification
const token = generateToken({
  agentId: 'agent-123',
  expiresIn: 3600,  // 1 hour
  secret: 'your-secret'
})

// Later, verify the token
const result = verifyToken(token, 'your-secret')
// Returns: { valid: boolean, payload?: { agentId, exp, iat } }
```

## Use Cases

- **Agent-only NFT mints** - Reserve drops for AI agents
- **API access control** - Endpoints only agents should access
- **Agent-to-agent auth** - Verify participants in agent networks
- **Agent gaming** - Games for autonomous players
- **Agent airdrops** - Token distributions for verified agents

## Integration Examples

### Express.js Middleware

```typescript
import { createChallenge, verifyChallenge } from 'nohumanallowed'

app.get('/challenge', (req, res) => {
  const challenge = createChallenge({ difficulty: 4, expiresIn: 60 })
  res.json(challenge)
})

app.post('/verify', (req, res) => {
  const { prefix, nonce, target, expiresAt } = req.body
  const result = verifyChallenge({ prefix, nonce, target, expiresAt })
  
  if (result.valid) {
    // Agent verified! Grant access...
    res.json({ success: true })
  } else {
    res.status(401).json({ error: result.error })
  }
})
```

### OpenClaw Skill

The skill is available at `skill/` for OpenClaw agents:

```bash
# In your skill's script
./solve.sh "$PREFIX" "$TARGET"
# Outputs: nonce on success
```

## Security Notes

- Always use `secret` for signed challenges in production
- Set appropriate `expiresIn` to prevent replay attacks
- Difficulty 4 is recommended for most use cases
- The proof-of-work is CPU-bound, not parallelizable per challenge

## License

Apache 2.0 - Free to use, attribution required.

Powered by the [Shellborn Collective](https://shellborn.io) 🦞

---

**Links:**
- GitHub: https://github.com/borninshell/nohumanallowed
- NPM: https://www.npmjs.com/package/nohumanallowed
- Shellborn: https://shellborn.io
