captcha-relay

# CAPTCHA Relay v2

Solve CAPTCHAs by relaying them to a human. Two modes available.

## Modes

### Screenshot Mode (default) — No infrastructure needed

Grid overlay screenshot → send image to human via Telegram → human replies with cell numbers → inject clicks.

- **Zero setup** beyond the skill itself. No Tailscale, no tunnels, no relay server.
- Works for **any** CAPTCHA type (reCAPTCHA, hCaptcha, sliders, text, etc.)
- Uses `sharp` for image processing + CDP for screenshots and click injection.

```bash
node index.js                       # screenshot mode (default)
node index.js --mode screenshot     # explicit
node index.js --screenshot          # legacy alias
```

```js
const { solveCaptchaScreenshot } = require('./index');
const capture = await solveCaptchaScreenshot({ cdpPort: 18800 });
// capture.imagePath — annotated screenshot to send to human
// capture.prompt — text prompt for the human
```

### Token Relay Mode — Requires network access

Detects CAPTCHA type + sitekey → serves real widget on relay page → human solves natively → token injected via CDP.

- Requires **Tailscale** or a **tunnel** (localtunnel/cloudflared) so the human's device can reach the relay server.
- Produces a proper CAPTCHA token — more reliable for reCAPTCHA v2, hCaptcha, Turnstile.
- Best when you have Tailscale already set up.

```bash
node index.js --mode relay              # with localtunnel
node index.js --mode relay --no-tunnel  # with Tailscale/LAN
```

```js
const { solveCaptcha } = require('./index');
const result = await solveCaptcha({ cdpPort: 18800, useTunnel: false });
// result.relayUrl — URL to send to human
// result.token — solved CAPTCHA token
```

## When to Use Each

| Scenario | Mode |
|----------|------|
| Quick & easy, no setup | `screenshot` |
| Any CAPTCHA type (sliders, text, etc.) | `screenshot` |
| Known CAPTCHA with sitekey (reCAPTCHA, hCaptcha, Turnstile) | `relay` |
| Tailscale already configured | `relay` |
| No network access to host | `screensho...

# captcha-relay

Human-in-the-loop CAPTCHA solving. No third-party solving services. No API keys. Just you and your phone.

## Two Modes

### 📸 Screenshot Mode (default) — Zero infrastructure

Captures the CAPTCHA as a screenshot with a numbered grid overlay, sends it to you (via Telegram, etc.), you reply with cell numbers, and clicks are injected into the browser.

**Works for any CAPTCHA type.** No network setup needed.

```bash
node index.js                   # screenshot mode is the default
node index.js --mode screenshot # explicit
```

### 🔑 Token Relay Mode — Native solving

Detects the CAPTCHA type and sitekey, serves the real CAPTCHA widget on a relay page, you solve it natively on your phone, and the token is injected back via CDP.

**Requires network access** (Tailscale or tunnel) so your phone can reach the relay server.

```bash
node index.js --mode relay              # with localtunnel
node index.js --mode relay --no-tunnel  # with Tailscale/LAN
```

## Quick Start

### Screenshot Mode (easiest)

```bash
cd captcha-relay
npm install
# Launch Chrome with CDP:
chromium --remote-debugging-port=18800

# In another terminal:
node index.js
# → Outputs annotated screenshot path as JSON
# → Send image to human, get cell numbers back, inject clicks
```

### Token Relay Mode

**With Tailscale (recommended):**

```bash
# Install Tailscale on both your server and phone
# See TAILSCALE.md for details

node index.js --mode relay --no-tunnel
# → Outputs relay URL as JSON
# → Open URL on phone, solve CAPTCHA, token auto-injected
```

**With localtunnel:**

```bash
node index.js --mode relay
# → Creates public tunnel URL automatically
```

## Module API

```js
const { solveCaptcha, solveCaptchaScreenshot, injectGridClicks } = require('captcha-relay');

// Screenshot mode
const capture = await solveCaptchaScreenshot({ cdpPort: 18800 });
// capture.imagePath, capture.prompt, capture.rows, capture.cols

// Token relay mode
const result = await solveCaptcha({ cdpPort: 1...