@biggora/claude-plugins 1.1.1 → 1.2.2

package/src/skills/captcha/references/captcha-types.md

@@ -0,0 +1,254 @@
+# CAPTCHA Types — Detection & Injection Patterns
+
+Reference for identifying which CAPTCHA is on a page and injecting the solved token.
+
+---
+
+## reCAPTCHA v2 (Checkbox)
+
+The most common CAPTCHA. Shows a checkbox; sometimes shows an image grid challenge.
+
+### Detection
+```javascript
+// Returns sitekey if reCAPTCHA v2 is present, null otherwise
+const el = document.querySelector('.g-recaptcha, [data-sitekey]:not(.h-captcha):not(.cf-turnstile)');
+el?.dataset?.sitekey ?? null;
+
+// Alternative: extract from iframe src
+const frame = document.querySelector('iframe[src*="recaptcha"]');
+frame?.src?.match(/[?&]k=([^&]+)/)?.[1] ?? null;
+```
+
+### Parameters to collect
+- `sitekey` — the `data-sitekey` attribute on `.g-recaptcha`
+- `pageurl` — `window.location.href`
+
+### Token injection
+```javascript
+function injectRecaptchaV2(token) {
+  // Set the hidden response field (may be display:none — that's fine)
+  document.querySelectorAll('[name="g-recaptcha-response"]').forEach(el => {
+    el.value = token;
+  });
+
+  // Trigger the registered callback
+  if (window.___grecaptcha_cfg) {
+    Object.values(window.___grecaptcha_cfg.clients || {}).forEach(client => {
+      Object.keys(client).forEach(key => {
+        const widget = client[key];
+        if (widget && typeof widget.callback === 'function') {
+          widget.callback(token);
+        }
+      });
+    });
+  }
+
+  // Fallback: look for a global callback name in the render call
+  // Search page source for: grecaptcha.render(..., { callback: 'FUNCTION_NAME' })
+}
+```
+
+### Notes
+- If injection has no effect, check if there's a `grecaptcha.render(element, { callback: fn })` call
+  in the page source — call that function with the token directly.
+- Some sites wrap the callback in `window.onRecaptchaSuccess` or similar. Search the page for
+  `grecaptcha` to find where the callback is registered.
+
+---
+
+## reCAPTCHA v2 Invisible
+
+No visible checkbox. Triggered programmatically with `grecaptcha.execute()`. Produces the same
+token format as v2 checkbox.
+
+### Detection
+```javascript
+// Invisible reCAPTCHA has no visible .g-recaptcha widget
+// Look for grecaptcha.execute() calls or a render with { size: 'invisible' }
+const src = document.documentElement.innerHTML;
+const isInvisible = src.includes("size: 'invisible'") || src.includes('"invisible"');
+```
+
+### Solve with `--invisible` flag
+```bash
+python scripts/solve_captcha.py --type recaptcha-v2 --invisible --sitekey KEY --pageurl URL
+```
+
+### Token injection
+Same as v2 checkbox injection above.
+
+---
+
+## reCAPTCHA v3
+
+Score-based, invisible. No user interaction at all. The site calls
+`grecaptcha.execute(sitekey, {action: 'actionName'})` in its JS, then validates the returned
+score server-side (scores range 0.0–1.0; bots score low).
+
+### Detection
+```javascript
+// Look for grecaptcha.execute with a sitekey in the page source
+// There is no visible widget — detection is by source inspection
+const src = document.documentElement.innerHTML;
+const match = src.match(/grecaptcha\.execute\(['"]([^'"]+)['"]/);
+match?.[1] ?? null;  // sitekey if found
+```
+
+Or grep the page HTML for `grecaptcha.execute(` to find the sitekey and action name.
+
+### Parameters
+- `sitekey` — from the `grecaptcha.execute('SITEKEY', ...)` call
+- `pageurl` — `window.location.href`
+- `action` — the action string in `{action: 'NAME'}`, e.g. `verify`, `submit`, `login`
+- `min_score` — request a score of at least this value (default 0.5; lower = easier to solve)
+
+### Solve
+```bash
+python scripts/solve_captcha.py --type recaptcha-v3 \
+  --sitekey SITEKEY --pageurl URL \
+  --action submit --min-score 0.7
+```
+
+### Token injection
+v3 tokens are typically consumed by an AJAX call, not a visible form field. The site expects
+the token in a specific request parameter. Two approaches:
+
+1. **Intercept the form submit** — inject the token before the AJAX fires:
+```javascript
+// Override grecaptcha.execute to return your solved token
+window.grecaptcha.execute = () => Promise.resolve(TOKEN);
+```
+
+2. **Set the hidden field** if the site stores the token in an input before submitting:
+```javascript
+document.querySelectorAll('[name="g-recaptcha-response"], [name="token"]').forEach(el => {
+  el.value = TOKEN;
+});
+```
+
+---
+
+## hCaptcha
+
+Common on Cloudflare-protected and privacy-focused sites.
+
+### Detection
+```javascript
+const el = document.querySelector('.h-captcha, [data-hcaptcha-sitekey]');
+el?.dataset?.sitekey ?? document.querySelector('[data-sitekey].h-captcha')?.dataset?.sitekey ?? null;
+```
+
+### Solve
+```bash
+python scripts/solve_captcha.py --type hcaptcha --sitekey KEY --pageurl URL
+```
+
+### Token injection
+```javascript
+function injectHcaptcha(token) {
+  // Set the response field
+  document.querySelectorAll('[name="h-captcha-response"]').forEach(el => {
+    el.value = token;
+  });
+
+  // Trigger hCaptcha callback
+  if (window.hcaptcha) {
+    // Some sites register a callback via hcaptcha.render
+    const iframes = document.querySelectorAll('iframe[src*="hcaptcha"]');
+    // Try the global callback if defined
+    if (typeof window.onHcaptchaSuccess === 'function') window.onHcaptchaSuccess(token);
+  }
+}
+```
+
+If the above doesn't trigger the form to proceed, look for `data-callback` on the `.h-captcha`
+element and call that function by name:
+```javascript
+const callbackName = document.querySelector('[data-callback]')?.dataset?.callback;
+if (callbackName && window[callbackName]) window[callbackName](token);
+```
+
+---
+
+## Cloudflare Turnstile
+
+Cloudflare's newer CAPTCHA, launched 2022. Invisible by default.
+
+### Detection
+```javascript
+const el = document.querySelector('.cf-turnstile');
+el?.dataset?.sitekey ?? null;
+```
+
+### Solve
+```bash
+python scripts/solve_captcha.py --type turnstile --sitekey KEY --pageurl URL
+```
+
+### Token injection
+```javascript
+function injectTurnstile(token) {
+  document.querySelectorAll('[name="cf-turnstile-response"]').forEach(el => {
+    el.value = token;
+  });
+
+  // Some sites use a callback
+  const callbackName = document.querySelector('.cf-turnstile')?.dataset?.callback;
+  if (callbackName && window[callbackName]) window[callbackName](token);
+}
+```
+
+---
+
+## Image / Text CAPTCHA
+
+Classic distorted text or simple math CAPTCHAs. Send the image, get text back.
+
+### Detection
+```javascript
+// Look for an image element with "captcha" in its src or alt
+document.querySelector('img[src*="captcha" i], img[alt*="captcha" i]')?.src ?? null;
+```
+
+### Capture the image
+```python
+# With Playwright: screenshot just the CAPTCHA element
+captcha_el = page.query_selector('img[alt*="captcha" i]')
+captcha_el.screenshot(path="captcha.png")
+```
+
+Or fetch the image URL directly:
+```python
+import urllib.request
+img_url = page.evaluate("document.querySelector('img[src*=\"captcha\"]').src")
+urllib.request.urlretrieve(img_url, "captcha.png")
+```
+
+### Solve
+```bash
+python scripts/solve_captcha.py --type image --image captcha.png
+```
+
+### Use the result
+```javascript
+// The solved token is the text answer, not a long JWT
+document.querySelector('input[name*="captcha" i]').value = SOLVED_TEXT;
+```
+
+### Tips for better accuracy
+- Crop to just the CAPTCHA image (no padding or surrounding UI)
+- Convert to grayscale and increase contrast before sending
+- If the CAPTCHA is math (e.g. "3 + 4 = ?"), the solver returns "7" as text
+
+---
+
+## Quick Reference Table
+
+| Type | Detect selector | Key field to inject | Callback trigger |
+|------|----------------|---------------------|-----------------|
+| reCAPTCHA v2 | `.g-recaptcha` | `[name="g-recaptcha-response"]` | `___grecaptcha_cfg.clients[n][k].callback(token)` |
+| reCAPTCHA v2 invisible | script source | `[name="g-recaptcha-response"]` | same as v2 |
+| reCAPTCHA v3 | script source | hidden input or AJAX param | override `grecaptcha.execute` |
+| hCaptcha | `.h-captcha` | `[name="h-captcha-response"]` | `[data-callback]` function |
+| Turnstile | `.cf-turnstile` | `[name="cf-turnstile-response"]` | `[data-callback]` function |
+| Image | `img[src*=captcha]` | text input near image | n/a |

package/src/skills/captcha/references/services.md

@@ -0,0 +1,172 @@
+# CAPTCHA Solving Services
+
+Comparison of the three major services supported by `solve_captcha.py`.
+
+All three use the same API endpoint format (2captcha-compatible), so you can switch
+between them with only the `--service` flag.
+
+---
+
+## 2captcha
+
+**Website:** https://2captcha.com
+**`--service` flag:** `2captcha` (default)
+
+The most widely documented and supported service. Operates since 2009.
+Uses a combination of human workers and AI for solving.
+
+### Pricing (approximate)
+| Type | Per 1,000 |
+|------|-----------|
+| reCAPTCHA v2 | $1.00–$1.50 |
+| reCAPTCHA v3 | $2.00–$3.00 |
+| hCaptcha | $1.50–$2.00 |
+| Turnstile | $1.00–$1.50 |
+| Image/text | $0.50–$1.00 |
+
+### Getting started
+1. Sign up at https://2captcha.com/register
+2. Add funds (minimum ~$3, accepts cards and crypto)
+3. Copy your API key from https://2captcha.com/enterpage
+
+### Free testing
+2captcha offers a demo mode at https://2captcha.com/demo/ — you can test all CAPTCHA
+types without spending credits. The demo page at https://2captcha.com/demo/recaptcha-v2
+is useful for verifying your integration works.
+
+### Checking balance
+```bash
+curl "https://2captcha.com/res.php?key=YOUR_KEY&action=getbalance"
+# → 4.25  (balance in USD)
+```
+
+### Average solve times
+- reCAPTCHA v2: 20–35s
+- reCAPTCHA v3: 30–60s
+- hCaptcha: 20–40s
+- Image: 5–15s
+
+---
+
+## CapMonster Cloud
+
+**Website:** https://capmonster.cloud
+**`--service` flag:** `capmonster`
+
+AI-powered service (no human workers). Faster and cheaper than 2captcha for most types.
+Uses machine learning models that have been trained on CAPTCHA datasets.
+
+### Pricing (approximate)
+| Type | Per 1,000 |
+|------|-----------|
+| reCAPTCHA v2 | $0.60 |
+| reCAPTCHA v3 | $1.50 |
+| hCaptcha | $0.80 |
+| Turnstile | $0.60 |
+| Image/text | $0.30 |
+
+### Getting started
+1. Sign up at https://capmonster.cloud
+2. Add funds (minimum $2)
+3. Copy API key from dashboard
+
+### API compatibility note
+CapMonster uses the same `/in.php` and `/res.php` endpoint format as 2captcha.
+The `solve_captcha.py` script handles the URL switching automatically via `--service capmonster`.
+
+### Average solve times
+- reCAPTCHA v2: 10–25s
+- hCaptcha: 15–30s
+- Image: 2–8s
+
+---
+
+## Anti-Captcha
+
+**Website:** https://anti-captcha.com
+**`--service` flag:** `anticaptcha`
+
+One of the original CAPTCHA solving services. Good uptime and reliable for bulk tasks.
+
+### Pricing (approximate)
+| Type | Per 1,000 |
+|------|-----------|
+| reCAPTCHA v2 | $0.70 |
+| reCAPTCHA v3 | $1.80 |
+| hCaptcha | $1.00 |
+| Image/text | $0.70 |
+
+### Getting started
+1. Sign up at https://anti-captcha.com
+2. Add funds
+3. Copy API key from Account Settings
+
+---
+
+## Choosing a Service
+
+| If you need... | Use |
+|---------------|-----|
+| Best documentation & community | 2captcha |
+| Lowest cost + fastest for reCAPTCHA v2 | CapMonster |
+| Bulk image CAPTCHA at low cost | CapMonster or Anti-Captcha |
+| reCAPTCHA v3 reliability | 2captcha (more worker capacity) |
+| Free credits to test | 2captcha ($1 signup bonus occasionally) |
+
+---
+
+## Using Multiple Services (Fallback)
+
+If one service is down or out of credits, fall back to another:
+
+```python
+import json, subprocess, os
+
+def solve_with_fallback(captcha_type, sitekey, pageurl):
+    services = ["2captcha", "capmonster", "anticaptcha"]
+    for service in services:
+        key_env = f"CAPTCHA_API_KEY_{service.upper().replace('-', '_')}"
+        api_key = os.environ.get(key_env) or os.environ.get("CAPTCHA_API_KEY")
+        if not api_key:
+            continue
+        result = subprocess.run(
+            ["python", "scripts/solve_captcha.py",
+             "--type", captcha_type, "--sitekey", sitekey, "--pageurl", pageurl,
+             "--service", service, "--api-key", api_key],
+            capture_output=True, text=True
+        )
+        data = json.loads(result.stdout)
+        if data.get("success"):
+            return data["token"]
+        print(f"[captcha] {service} failed: {data.get('error')} — trying next service")
+    raise RuntimeError("All CAPTCHA solving services failed")
+```
+
+---
+
+## Checking Your Balance
+
+```bash
+# 2captcha
+curl "https://2captcha.com/res.php?key=YOUR_KEY&action=getbalance"
+
+# CapMonster
+curl "https://api.capmonster.cloud/res.php?key=YOUR_KEY&action=getbalance"
+
+# Anti-Captcha
+curl "https://api.anti-captcha.com/res.php?key=YOUR_KEY&action=getbalance"
+```
+
+---
+
+## Error Codes
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| `ERROR_ZERO_BALANCE` | Account has no credits | Add funds at service dashboard |
+| `ERROR_NO_SLOT_AVAILABLE` | Service overloaded | Retry in a few minutes |
+| `ERROR_WRONG_CAPTCHA_ID` | Invalid task ID | Bug in code — report |
+| `ERROR_CAPTCHA_UNSOLVABLE` | Solver gave up | Retry; if recurring, try another service |
+| `ERROR_WRONG_USER_KEY` | Bad API key | Check key, no trailing spaces |
+| `CAPCHA_NOT_READY` | Still processing | Normal — keep polling |
+| `ERROR_IP_BANNED` | Your IP is blocked | Contact service support |

package/src/skills/captcha/references/stealth.md

@@ -0,0 +1,238 @@
+# Avoiding Bot Detection After Passing CAPTCHA
+
+Passing the CAPTCHA itself is often not enough — the site may still flag and block your
+session based on browser fingerprinting or behavioral signals. This document covers the
+most common detection vectors and how to mitigate them.
+
+---
+
+## Why Sites Still Block After CAPTCHA
+
+Modern anti-bot systems (Cloudflare, PerimeterX, DataDome, Kasada) score requests on
+multiple signals **beyond** the CAPTCHA solution:
+
+1. **Browser fingerprint** — headless Chrome has telltale JS properties
+2. **Mouse / interaction patterns** — no mouse movement, instant form fills
+3. **Request headers** — missing or inconsistent Accept-Language, Referer, etc.
+4. **IP reputation** — data center IPs are pre-flagged
+5. **Cookie / session age** — fresh sessions with no history look suspicious
+6. **Timing** — solving a CAPTCHA in 15s (via API) and submitting instantly
+
+---
+
+## Playwright Stealth Mode
+
+The single most impactful change: install and use `playwright-stealth` to patch the
+headless detection markers.
+
+```bash
+pip install playwright-stealth
+```
+
+```python
+from playwright.sync_api import sync_playwright
+from playwright_stealth import stealth_sync
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page()
+    stealth_sync(page)  # patches ~30 fingerprinting vectors
+    page.goto("https://example.com")
+```
+
+### What stealth patches
+- `navigator.webdriver` — set to `undefined` instead of `true`
+- Chrome runtime properties — adds `chrome.runtime` and related objects
+- Plugin / mimeType arrays — populated instead of empty
+- `navigator.languages` — realistic value
+- `window.outerWidth/Height` — matches viewport
+- Canvas and WebGL fingerprints — some randomization
+
+---
+
+## Use a Real Browser Profile (Non-Headless)
+
+If stealth mode isn't enough, launch with a real user data directory so the browser
+has history, cookies, and extensions like a real user:
+
+```python
+import os
+from playwright.sync_api import sync_playwright
+
+user_data = os.path.expanduser("~/.config/captcha-automation-profile")
+
+with sync_playwright() as p:
+    browser = p.chromium.launch_persistent_context(
+        user_data_dir=user_data,
+        headless=False,  # visible window bypasses some checks
+        args=["--disable-blink-features=AutomationControlled"],
+    )
+    page = browser.new_page()
+    page.goto("https://example.com")
+```
+
+The `--disable-blink-features=AutomationControlled` flag prevents the
+`navigator.webdriver` property from being set to `true`.
+
+---
+
+## Realistic Request Headers
+
+Missing or wrong headers are a major signal. Set these before navigating:
+
+```python
+page.set_extra_http_headers({
+    "Accept-Language": "en-US,en;q=0.9",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    "Sec-Fetch-Site": "none",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-User": "?1",
+    "Sec-Fetch-Dest": "document",
+    "Upgrade-Insecure-Requests": "1",
+})
+```
+
+Also set a realistic User-Agent:
+```python
+browser = p.chromium.launch()
+context = browser.new_context(
+    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+               "AppleWebKit/537.36 (KHTML, like Gecko) "
+               "Chrome/124.0.0.0 Safari/537.36",
+    viewport={"width": 1280, "height": 720},
+    locale="en-US",
+    timezone_id="America/New_York",
+)
+page = context.new_page()
+```
+
+---
+
+## Add Human-Like Delays
+
+```python
+import time, random
+
+def human_delay(min_ms=800, max_ms=2500):
+    """Sleep for a random human-like duration."""
+    time.sleep(random.uniform(min_ms, max_ms) / 1000)
+
+# Between navigation and form fill
+page.goto(url)
+human_delay(1000, 3000)
+
+# Between filling each field
+page.fill('#email', 'user@example.com')
+human_delay(300, 900)
+page.fill('#password', 'secret')
+human_delay(500, 1500)
+
+# After CAPTCHA solve, before form submit
+inject_captcha_token(page, token)
+human_delay(800, 2000)
+page.click('button[type=submit]')
+```
+
+---
+
+## Mouse Movement Simulation
+
+Sites sometimes require mouse activity before accepting a form submit:
+
+```python
+import asyncio, random, math
+
+async def move_mouse_naturally(page, x_end, y_end, steps=20):
+    """Simulate curved mouse movement to a target."""
+    box = await page.evaluate("({x: window.innerWidth/2, y: window.innerHeight/2})")
+    x_start, y_start = box["x"], box["y"]
+
+    for i in range(steps):
+        t = i / steps
+        # Quadratic bezier curve
+        cx = x_start + random.randint(-50, 50)
+        cy = y_start + random.randint(-50, 50)
+        x = (1-t)**2 * x_start + 2*(1-t)*t * cx + t**2 * x_end
+        y = (1-t)**2 * y_start + 2*(1-t)*t * cy + t**2 * y_end
+        await page.mouse.move(x, y)
+        await asyncio.sleep(random.uniform(0.01, 0.04))
+```
+
+---
+
+## Residential Proxies
+
+Data center IPs (AWS, GCP, Azure, VPS) are pre-flagged by most anti-bot systems.
+Use residential proxies for better success rates:
+
+```python
+browser = p.chromium.launch(
+    proxy={
+        "server": "http://proxy.provider.com:8080",
+        "username": "user",
+        "password": "pass",
+    }
+)
+```
+
+Residential proxy providers: Bright Data, Oxylabs, Smartproxy, IPRoyal.
+Expect to pay $5–$15/GB for residential IPs vs $0.50/GB for data center IPs.
+
+---
+
+## Viewport and Screen Size
+
+Headless browsers default to unusual viewport sizes. Match common desktop dimensions:
+
+```python
+context = browser.new_context(
+    viewport={"width": 1920, "height": 1080},
+    device_scale_factor=1,
+    is_mobile=False,
+)
+```
+
+---
+
+## Session Warmup
+
+Fresh sessions with no cookies or history are suspicious. Before hitting the target page:
+
+1. Navigate to the homepage first
+2. Wait a few seconds
+3. Click a link or scroll
+4. Then go to the page you want to interact with
+
+```python
+page.goto("https://example.com")
+time.sleep(random.uniform(2, 5))
+# scroll down a bit
+page.evaluate("window.scrollBy(0, Math.floor(Math.random() * 300 + 100))")
+time.sleep(random.uniform(1, 3))
+page.goto("https://example.com/login")
+```
+
+---
+
+## Detection Test
+
+Before automating a target site, test your browser fingerprint at:
+- https://bot.sannysoft.com — headless Chrome detection tests
+- https://pixelscan.net — comprehensive fingerprint check
+- https://abrahamjuliot.github.io/creepjs/ — advanced entropy fingerprinting
+
+If these sites detect you as a bot, apply more stealth measures before attempting
+the actual target.
+
+---
+
+## Summary Checklist
+
+- [ ] Use `playwright-stealth` (or `--disable-blink-features=AutomationControlled`)
+- [ ] Set realistic User-Agent, viewport, locale, timezone
+- [ ] Set Accept-Language and other headers
+- [ ] Add random delays between actions (800ms–3s)
+- [ ] Move mouse before clicking submit
+- [ ] Use residential proxy if data center IP is blocked
+- [ ] Warm up session before hitting the CAPTCHA page
+- [ ] Inject CAPTCHA token and wait 1–2s before submitting