johnalbertini14-glitch/openclaw-skills / skills/0xclanky/captcha-relay
captcha-relay
FlaggedHuman-in-the-loop CAPTCHA solving with two modes: screenshot (default, zero infrastructure) and token relay (requires network access). Screenshot mode captures the page with a grid overlay, sends it to the human, and injects clicks based on their reply. Token relay mode detects CAPTCHA type + sitekey, serves the real widget on a relay page for native solving, and injects the token via CDP.
| File | Kind | Size |
|---|---|---|
| ARCHITECTURE.md | markdown | 4.2 KB |
| README.md | markdown | 4.0 KB |
| SKILL.md | skill md | 3.6 KB |
| TAILSCALE.md | markdown | 3.0 KB |
| _meta.json | config | 458 B |
| browser-relay-cli.js | script | 981 B |
| fallback/screenshot.js | script | 5.2 KB |
| index.js | script | 5.4 KB |
| lib/browser-relay.js | script | 7.9 KB |
| lib/cdp.js | script | 2.8 KB |
| lib/detect.js | script | 2.8 KB |
| lib/inject.js | script | 4.5 KB |
| lib/server.js | script | 2.6 KB |
| lib/templates/browser-relay.html | other | 7.5 KB |
| lib/templates/hcaptcha.html | other | 1.8 KB |
| lib/templates/recaptcha-v2.html | other | 1.9 KB |
| lib/templates/turnstile.html | other | 1.8 KB |
| lib/tunnel.js | script | 4.2 KB |
| package-lock.json | manifest | 17.2 KB |
| package.json | manifest | 443 B |
ARCHITECTURE.md
View on GitHub# CAPTCHA Relay v2 — Architecture
## Overview
Token-based CAPTCHA relay: extract sitekey from automated browser, serve a relay page with the real CAPTCHA widget, human solves on phone, token relayed back and injected via CDP.
## Flow
```
Agent Browser → CAPTCHA detected
↓
Extract type + sitekey (CDP page target)
↓
Start relay HTTP server (random port)
↓
Start tunnel (localtunnel / cloudflared / Tailscale)
↓
Send URL to human (Telegram inline button)
↓
Human opens on phone → solves CAPTCHA widget
↓
Token POSTed to /token → written to /tmp/captcha-relay-token.txt
↓
Inject token into browser page (CDP page target)
↓
Cleanup (stop server + tunnel)
```
## File Structure
```
skills/captcha-relay/
├── SKILL.md # Skill manifest
├── ARCHITECTURE.md # This file
├── TAILSCALE.md # Tailscale setup guide
├── package.json
├── index.js # Main orchestrator (CLI + module)
├── lib/
│ ├── cdp.js # CDP client (WebSocket, page targets)
│ ├── detect.js # CAPTCHA detection + sitekey extraction
│ ├── server.js # HTTP relay server
│ ├── tunnel.js # Tunnel management (localtunnel, cloudflared)
│ ├── inject.js # Token injection back into browser
│ └── templates/ # HTML relay pages
│ ├── recaptcha-v2.html
│ ├── hcaptcha.html
│ └── turnstile.html
└── fallback/
└── screenshot.js # Screenshot grid fallback (v1 style)
```
## Key Modules
### detect.js
Connects to CDP via page target (not browser-level WS URL). Evaluates JS to find CAPTCHA widgets by class/data-sitekey attributes and iframe src parsing.
### server.js
Minimal HTTP server (no Express). Serves templated CAPTCHA page on GET /, receives token on POST /token. Writes token to `/tmp/captcha-relay-token.txt` and resolves a Promise.
### tunnel.js
Tries localtunnel (via `npx localtunnel`) first, falls back to cloudflared, then local IP. Returns `{ url, process, isLocal, method }`.
### inject.js
Connects to CDP page target and injects token via:
- Setting textarea value (`#g-recaptcha-response`, etc.)
- Dispatching input events
- Calling registered callbacks (data-callback attr, `___grecaptcha_cfg` internal, etc.)
### Templates
Each HTML template loads the provider's JS SDK, renders the widget with the extracted sitekey, and POSTs the token back to `/token` on solve. Dark theme, mobile-optimized.
## Domain Matching
| Provider | Client Domain Check | Token Relay Status |
|----------|--------------------|--------------------|
| reCAPTCHA v2 | Yes — but **works anyway** for many sites | ✅ Tested working |
| hCaptcha | No client check | ✅ Should work reliably |
| Turnstile | Yes | ⚠️ Untested |
**Lesson learned**: reCAPTCHA v2 token relay works better than expected. Tested with Google's demo — the widget renders on any domain and the token is accepted.
## Lessons Learned (v2 Development)
### Tunneling
- **cloudflared**: Too heavy for constrained machines (ARM, low-RAM). Binary is large and resource-hungry.
- **localhost.run**: Free tier has broken TLS certificates. Unusable.
- **localtunnel**: Works well via `npx localtunnel`. Free, no install. Downside: shows a splash/interstitial page on first visit ("Click to Continue"). Minor UX annoyance.
- **Tailscale**: Recommended for production. No tunnel needed — devices on the same Tailnet can reach the relay server directly via Tailscale IP. No splash pages, always-on. See TAILSCALE.md.
### CDP Connection
- Must use **page-level** WebSocket URL from `/json/list`, not the browser-level URL from `/json/version`. The browser-level connection can't evaluate JS in page context.
### Token Injection
- Setting textarea value alone isn't enough — must also trigger the callback. Walking `___grecaptcha_cfg.clients` tree to find the callback function works for reCAPTCHA v2.
## Dependencies
- `ws` — WebSocket client for CDP
- `sharp` — image processing (screenshot fallback mode)
- `localtunnel` — tunnel (via npx, not installed)
- `cloudflared` — system binary (optional fallback)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |