Proposition: Browser CAPTCHA Assist - Intervention Humaine en Temps Réel

Date: 03-02-2026 Status: PROPOSITION Complexité: HAUTE (WebRTC/WebSocket streaming)

Problème

Quand le browser-connector rencontre un anti-robot (CAPTCHA image, slider, puzzle, reCAPTCHA, etc.), l'automation est bloquée. Il faut permettre à l'utilisateur d'intervenir manuellement.

Solution Proposée

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    CAPTCHA ASSIST - Flux Temps Réel                          │
│                                                                              │
│  ┌─────────────┐     WebSocket      ┌─────────────────┐                     │
│  │   Frontend  │◄──────────────────►│ Browser-Connector│                     │
│  │  (Overlay)  │   frames + events  │   (Playwright)   │                     │
│  └─────────────┘                    └─────────────────┘                     │
│        │                                    │                                │
│        │ User clicks/drags                  │ Screenshot stream              │
│        ▼                                    ▼                                │
│  ┌─────────────┐                    ┌─────────────────┐                     │
│  │  Canvas     │                    │  Page.screenshot │                     │
│  │  Interactif │                    │  (zone CAPTCHA)  │                     │
│  └─────────────┘                    └─────────────────┘                     │
└─────────────────────────────────────────────────────────────────────────────┘

Workflow

1. Détection CAPTCHA - Le scraper détecte un CAPTCHA (selector connu ou AI detection)
2. Pause & Notification - Pause l'automation, notifie l'user (push/webhook)
3. Stream Zone - Ouvre un WebSocket qui envoie des screenshots de la zone CAPTCHA (5-10 fps)
4. Overlay Frontend - L'user voit la zone dans un overlay interactif
5. Actions User - L'user clique/drag sur le canvas, les coords sont envoyées au backend
6. Playwright Execute - Le backend traduit en page.mouse.click(x, y) ou page.mouse.move() + drag
7. Validation - Détecte si CAPTCHA résolu, reprend l'automation

API Endpoints

// Démarrer une session d'assistance CAPTCHA
POST /api/captcha-assist/start
{
  "service": "linkedin",
  "region"?: { "x": 100, "y": 200, "width": 400, "height": 300 },  // Zone CAPTCHA
  "selector"?: ".captcha-container"  // Ou auto-detect
}
// Response: { "sessionId": "xxx", "wsUrl": "wss://browser.33800.../captcha/xxx" }

// WebSocket: /api/captcha-assist/:sessionId
// Server → Client: { "type": "frame", "image": "base64...", "timestamp": 123 }
// Client → Server: { "type": "click", "x": 150, "y": 80 }
// Client → Server: { "type": "drag", "from": { "x": 50, "y": 50 }, "to": { "x": 200, "y": 50 } }
// Client → Server: { "type": "done" }  // User indique qu'il a fini
// Server → Client: { "type": "resolved", "success": true }

// Terminer la session
POST /api/captcha-assist/end
{
  "sessionId": "xxx"
}

Composant Frontend

// CaptchaAssist.tsx
interface CaptchaAssistProps {
  sessionId: string;
  onResolved: () => void;
  onCancel: () => void;
}

// Affiche:
// - Canvas avec le stream de la zone CAPTCHA
// - Curseur synchronisé
// - Boutons: "J'ai fini" / "Annuler"
// - Instructions selon type CAPTCHA détecté

Types de CAPTCHA supportés

Détection automatique CAPTCHA

// Dans le scraper, après chaque action:
async function checkForCaptcha(page: Page): Promise<CaptchaInfo | null> {
  // Patterns connus
  const captchaSelectors = [
    'iframe[src*="recaptcha"]',
    'iframe[src*="hcaptcha"]',
    '.captcha-container',
    '#captcha',
    '[class*="captcha"]',
    '.challenge-container'
  ];

  for (const selector of captchaSelectors) {
    const el = await page.$(selector);
    if (el) {
      const bbox = await el.boundingBox();
      return { type: 'detected', selector, bbox };
    }
  }

  // Ou via AI (YOLO trained on CAPTCHA patterns)
  // ...

  return null;
}

Options de notification

Quand un CAPTCHA est détecté:

1. WebSocket actif → Notification immédiate dans l'UI
2. Push notification → Via notify_send MCP tool
3. Webhook → Appel URL configurée
4. Email → Via Mailjet (si configuré)

Configuration utilisateur

// Dans browser_credentials ou settings séparées
{
  "captcha_handling": "pause_and_notify" | "auto_solve" | "fail",
  "captcha_timeout": 300000,  // 5 min pour résoudre
  "notify_channels": ["push", "webhook"],
  "webhook_url": "https://..."
}

Sécurité

• Session WebSocket authentifiée (même JWT que l'API)
• Timeout automatique (5 min par défaut)
• Rate limit sur les events (max 20 events/sec)
• Logs audit des interventions manuelles

Complexité & Risques

Alternative plus simple (V1)

Si le streaming temps réel est trop complexe, on peut commencer par:

1. Screenshot statique de la zone CAPTCHA
2. L'user décrit ce qu'il voit ou clique sur l'image statique
3. On envoie les coords au backend qui clique
4. Refresh screenshot après chaque action
5. Loop jusqu'à résolu

→ Plus lent mais beaucoup plus simple à implémenter.

Estimation

• V1 (screenshots statiques): 1-2 jours
• V2 (streaming temps réel): 3-5 jours

Décision

Recommandation: Implémenter V1 d'abord (screenshots rafraîchis), puis V2 si besoin de fluidité.

En attente de validation avant implémentation.