# deldown captcha — Agent API

Headless integration for CLI tools and AI agents (opencode, Claude Code, …).
The site owner must enable **Agent-API** for the sitekey in the dashboard
(`PATCH /api/sites/:sitekey` with `{"allowApi": true}`), otherwise challenges
with `mode=api` are rejected with 403.

A solved token is a proof-of-work payload — no secret needed on the client.
The customer's backend verifies it via `/siteverify` exactly like a browser
widget token.

## Flow

```
1. GET  {base}/challenge?sitekey=SITEKEY&mode=api
   → { "algorithm": "SHA-256", "challenge": "<hex>", "maxnumber": 50000,
       "salt": "<hex>?…", "signature": "<hex>" }

2. Solve locally: find n ∈ [0, maxnumber] with
   sha256(salt + n) == challenge          (hex digest, n as decimal string)

3. Token = base64(JSON{
     algorithm, challenge, number: n, salt, signature
   })

4. Submit the token where the site expects it (form field
   `deldown-captcha-response`, or whatever the protected app defines).
```

## Ready-made solver

`bin/deldown-captcha.mjs` in the deldown captcha repo — zero dependencies,
needs only Node ≥ 18:

```bash
# print the token
node deldown-captcha.mjs https://captcha.deldown.de dcap_xxx

# solve + verify against your own backend key (round-trip check)
node deldown-captcha.mjs https://captcha.deldown.de dcap_xxx --verify dcs_xxx
```

## curl example

```bash
C=$(curl -fsS "https://captcha.deldown.de/challenge?sitekey=dcap_xxx&mode=api")
# … solve PoW on $C (see solver above) …
curl -X POST https://captcha.deldown.de/siteverify \
  -d secret=dcs_xxx -d response="$TOKEN"
```

## Rules and limits

- The challenge is single-use and expires (`challenge` response carries
  `maxnumber`; default TTL 5 min). Solve and submit promptly.
- Rate limits apply per IP: 60 challenges/min, 600 siteverify lookups/min.
  Solving is CPU work (~50 ms by default) — no need to be faster anyway.
- Every request is logged with an `api_mode` feature flag. Site owners can see
  agent traffic in their stats and can switch the API off at any time; in-flight
  tokens stop verifying immediately.
- No cookies, no tracking. The only thing stored is a salted, rotating hash of
  your IP (see PRIVACY.md).