fiptcha 0.1.5 → 0.1.6

package/README.md

@@ -56,6 +56,9 @@ Pass one of these values as `captchaType`:
 | `hcaptcha` | Interacts with the widget and solves supported image-grid challenges locally when required. |
 | `turnstile` | Performs active-browser interaction and waits for a token. It does not use the image-grid vision path. |
 
+> [!WARNING]
+> **3×3 image-grid stability is currently not good.** Dynamic 3×3 challenges, particularly those that replace tiles after a selection, may be unreliable. 4×4 static image-grid challenges are currently the more stable path.
+
 Fiptcha cannot guarantee that every challenge will be solvable. CAPTCHA providers can change their UI, challenge format, and risk checks independently of the visible widget.
 
 ## `solveLocalCaptcha(page, options)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiptcha",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Local CAPTCHA solving for browser automation. Built for Figranium, usable anywhere.",
   "main": "index.js",
   "license": "Apache-2.0",

package/src/captcha-grid-solver.js

@@ -8,7 +8,9 @@ const PROVIDERS = Object.freeze({
         cells: '.rc-imageselect-tile',
         submit: '#recaptcha-verify-button',
         noMatch: '#recaptcha-verify-button',
-        error: '.rc-imageselect-error-select-more, .rc-imageselect-error-dynamic-more, .rc-imageselect-incorrect-response',
+        // `error-dynamic-more` is also shown while replacement tiles are still
+        // expected. Treating it as a rejection aborts valid dynamic challenges.
+        error: '.rc-imageselect-error-select-more, .rc-imageselect-incorrect-response',
         cleanPrompt(text) {
             return text.replace(/select all (images|squares) with/ig, '')
                 .replace(/click verify once there are none left/ig, '')
@@ -16,10 +18,12 @@ const PROVIDERS = Object.freeze({
         }
     }),
     hcaptcha: Object.freeze({
-        framePatterns: ['hcaptcha.com/captcha', 'newassets.hcaptcha.com/captcha'],
-        instruction: '.prompt-text, .challenge-header .prompt-text, h2',
-        grid: '.task-grid',
-        cells: '.task-grid .task-image',
+        // Enterprise integrations may serve the iframe from a first-party
+        // asset host, so do not require an hcaptcha.com hostname.
+        framePatterns: ['hcaptcha.com', 'hcaptcha.html', 'hcaptcha-checkbox.html', 'frame=challenge', 'frame=checkbox'],
+        instruction: '.prompt-text, .challenge-header .prompt-text, .challenge-header h2, h2',
+        grid: '.task-grid, [class*="task-grid"]',
+        cells: '.task-grid .task-image, [class*="task-grid"] [class*="task-image"]',
         submit: '.button-submit, button[type="submit"]',
         noMatch: '.button-submit, button[type="submit"]',
         error: '.error-text, .challenge-error',
@@ -32,7 +36,8 @@ const PROVIDERS = Object.freeze({
 
 async function findChallengeFrame(page, adapter) {
     for (const frame of page.frames()) {
-        if (!adapter.framePatterns.some((pattern) => frame.url().includes(pattern))) continue;
+        const url = String(frame.url?.() || '').toLowerCase();
+        if (!adapter.framePatterns.some((pattern) => url.includes(pattern))) continue;
         if (await frame.locator(adapter.grid).first().isVisible({ timeout: 250 }).catch(() => false)) return frame;
     }
     return null;
@@ -81,18 +86,32 @@ function mapDetectionsToCells(detections, gridBox, cellBoxes, imageSize = null)
     for (const detection of detections) {
         const box = normalizeBox(detection);
         if (!box) continue;
-        const centerX = gridBox.x + (((box.xmin + box.xmax) / 2) * scaleX);
-        const centerY = gridBox.y + (((box.ymin + box.ymax) / 2) * scaleY);
-        const index = cellBoxes.findIndex((cell) => cell
-            && centerX >= cell.x && centerX <= cell.x + cell.width
-            && centerY >= cell.y && centerY <= cell.y + cell.height);
-        if (index >= 0) indexes.add(index);
+        const projected = {
+            left: gridBox.x + (box.xmin * scaleX),
+            top: gridBox.y + (box.ymin * scaleY),
+            right: gridBox.x + (box.xmax * scaleX),
+            bottom: gridBox.y + (box.ymax * scaleY)
+        };
+        const centerX = (projected.left + projected.right) / 2;
+        const centerY = (projected.top + projected.bottom) / 2;
+        cellBoxes.forEach((cell, index) => {
+            if (!cell) return;
+            const intersectionWidth = Math.max(0, Math.min(projected.right, cell.x + cell.width) - Math.max(projected.left, cell.x));
+            const intersectionHeight = Math.max(0, Math.min(projected.bottom, cell.y + cell.height) - Math.max(projected.top, cell.y));
+            const coverage = (intersectionWidth * intersectionHeight) / Math.max(1, cell.width * cell.height);
+            const containsCenter = centerX >= cell.x && centerX <= cell.x + cell.width
+                && centerY >= cell.y && centerY <= cell.y + cell.height;
+            // reCAPTCHA asks for every square containing part of an object, not
+            // merely the square containing the detector box's center.
+            if (containsCenter || coverage >= 0.08) indexes.add(index);
+        });
     }
     return [...indexes];
 }
 
 async function classifyGrid(frame, adapter, cells, label, seenTiles) {
     const modelLabel = normalizeModelLabel(label);
+    const mapped = new Set();
     const grid = frame.locator(adapter.grid).first();
     const gridBox = await grid.boundingBox().catch(() => null);
     if (gridBox) {
@@ -100,18 +119,7 @@ async function classifyGrid(frame, adapter, cells, label, seenTiles) {
         const detections = await captchaModelManager.detect(image, modelLabel);
         const cellBoxes = [];
         for (let index = 0; index < await cells.count(); index += 1) cellBoxes.push(await cells.nth(index).boundingBox().catch(() => null));
-        const mapped = mapDetectionsToCells(detections, gridBox, cellBoxes, pngDimensions(image));
-        if (mapped.length) {
-            const changed = [];
-            for (const index of mapped) {
-                const image = await cells.nth(index).screenshot({ type: 'png' });
-                const fingerprint = checksumBuffer(image);
-                if (seenTiles.get(index) === fingerprint) continue;
-                seenTiles.set(index, fingerprint);
-                changed.push(index);
-            }
-            return changed;
-        }
+        for (const index of mapDetectionsToCells(detections, gridBox, cellBoxes, pngDimensions(image))) mapped.add(index);
     }
 
     const selected = [];
@@ -121,21 +129,98 @@ async function classifyGrid(frame, adapter, cells, label, seenTiles) {
         const fingerprint = checksumBuffer(image);
         if (seenTiles.get(index) === fingerprint) continue;
         seenTiles.set(index, fingerprint);
-        if ((await captchaModelManager.detect(image, modelLabel)).length) selected.push(index);
+        // A whole-grid pass is fast and preserves objects spanning cell edges,
+        // while a tile pass retains detail on dense 4x4 grids. Fuse both: a
+        // partial grid result must not suppress tile-level matches elsewhere.
+        if (mapped.has(index) || (await captchaModelManager.detect(image, modelLabel)).length) selected.push(index);
     }
     return selected;
 }
 
-async function rememberClickedTile(cells, index, seenTiles) {
+async function rememberClickedTile(cells, index, seenTiles, beforeFingerprint = null) {
     // Clicking a CAPTCHA tile changes its rendered appearance (selection overlay,
     // border, checkmark, etc.). Remember that post-click state immediately so the
     // next sweep does not mistake the selection UI itself for a replacement image
     // and toggle an already-correct tile back off. A genuinely replaced tile will
     // still produce a different fingerprint on the next sweep.
-    const image = await cells.nth(index).screenshot({ type: 'png' }).catch(() => null);
+    const cell = cells.nth(index);
+    const currentFingerprint = await tileFingerprint(cell);
+    // A fast replacement may already be present by the time click() resolves.
+    // Do not mark that unseen image as processed.
+    if (beforeFingerprint && currentFingerprint && currentFingerprint !== beforeFingerprint) return;
+    const image = await cell.screenshot({ type: 'png' }).catch(() => null);
     if (image) seenTiles.set(index, checksumBuffer(image));
 }
 
+async function tileFingerprint(cell) {
+    const source = typeof cell.evaluate === 'function' ? await cell.evaluate((element) => {
+        const images = [...element.querySelectorAll('img')];
+        if (images.length) return images.map((image) => [image.currentSrc, image.src, image.style.transform].join('|')).join('\n');
+        const styled = [element, ...element.querySelectorAll('*')]
+            .map((candidate) => getComputedStyle(candidate).backgroundImage)
+            .filter((value) => value && value !== 'none');
+        return styled.join('\n');
+    }).catch(() => '') : '';
+    if (source) return checksumBuffer(Buffer.from(source));
+    const image = await cell.screenshot({ type: 'png' }).catch(() => null);
+    return image ? checksumBuffer(image) : null;
+}
+
+async function tileFingerprints(cells, indexes) {
+    const fingerprints = new Map();
+    for (const index of indexes) {
+        const fingerprint = await tileFingerprint(cells.nth(index));
+        if (fingerprint) fingerprints.set(index, fingerprint);
+    }
+    return fingerprints;
+}
+
+async function waitForTileReplacement(page, cells, before, deadline, timeout = 2500) {
+    const replacementDeadline = Math.min(deadline, Date.now() + timeout);
+    const pending = new Map(before);
+    let changed = false;
+    while (Date.now() < replacementDeadline) {
+        for (const [index, fingerprint] of pending) {
+            const current = await tileFingerprint(cells.nth(index));
+            if (current && current !== fingerprint) {
+                pending.delete(index);
+                changed = true;
+            }
+        }
+        if (!pending.size) {
+            // Let the replacement animation finish before inference.
+            await page.waitForTimeout(Math.min(250, Math.max(0, deadline - Date.now())));
+            return true;
+        }
+        await page.waitForTimeout(Math.min(100, Math.max(1, replacementDeadline - Date.now())));
+    }
+    return changed;
+}
+
+async function challengeSignature(frame, adapter) {
+    const grid = frame?.locator(adapter.grid).first();
+    const image = await grid?.screenshot({ type: 'png' }).catch(() => null);
+    if (!image) return null;
+    const prompt = normalizePrompt(adapter, await visibleText(frame, adapter.instruction));
+    const count = await frame.locator(adapter.cells).count().catch(() => 0);
+    return `${prompt}\n${count}\n${checksumBuffer(image)}`;
+}
+
+async function waitForSubmission(page, adapter, captchaType, previousSignature, deadline, waitForToken) {
+    const transitionDeadline = Math.min(deadline, Date.now() + 5000);
+    while (Date.now() < transitionDeadline) {
+        const token = await waitForToken(page, captchaType, 0);
+        if (token) return { token, transitioned: false };
+        const frame = await findChallengeFrame(page, adapter);
+        if (frame) {
+            const signature = await challengeSignature(frame, adapter);
+            if (previousSignature && signature && signature !== previousSignature) return { token: null, transitioned: true };
+        }
+        await page.waitForTimeout(Math.min(125, Math.max(1, transitionDeadline - Date.now())));
+    }
+    return { token: null, transitioned: false };
+}
+
 async function visibleText(frame, selector) {
     const matches = frame.locator(selector);
     for (let index = 0; index < await matches.count().catch(() => 0); index += 1) {
@@ -151,21 +236,24 @@ async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs
     if (!adapter) throw new Error(`No image-grid adapter for ${captchaType}`);
     const seenTiles = new Map();
     let previousPrompt = '';
-    for (let round = 0; round < 6 && Date.now() < deadline; round += 1) {
+    for (let round = 0; round < 12 && Date.now() < deadline; round += 1) {
         const frame = await findChallengeFrame(page, adapter);
         if (!frame) throw new Error(`${captchaType} image challenge frame disappeared`);
         const rejection = await visibleText(frame, adapter.error);
         if (rejection && round > 0) {
             throw new Error(`${captchaType} rejected the previous selection: ${rejection.replace(/\s+/g, ' ').trim()}`);
         }
-        const prompt = normalizePrompt(adapter, await visibleText(frame, adapter.instruction));
+        const instruction = await visibleText(frame, adapter.instruction);
+        const prompt = normalizePrompt(adapter, instruction);
+        const dynamic = captchaType === 'recaptcha_v2'
+            && /(?:none left|new images|replaced)/i.test(instruction);
         if (!prompt) throw new Error(`${captchaType} solver could not read the image challenge instruction`);
         if (prompt !== previousPrompt) {
             seenTiles.clear();
             previousPrompt = prompt;
         }
         let totalSelections = 0;
-        for (let sweep = 0; sweep < 4 && Date.now() < deadline; sweep += 1) {
+        for (let sweep = 0; sweep < 12 && Date.now() < deadline; sweep += 1) {
             const cells = frame.locator(adapter.cells);
             const count = await cells.count();
             if (![9, 16].includes(count)) throw new Error(`Unsupported ${captchaType} grid size (${count} cells)`);
@@ -173,21 +261,25 @@ async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs
             // Grid cells live inside a provider iframe. Let Playwright target the
             // element in that frame instead of sending a page-level mouse click:
             // the latter can miss the cell when iframe coordinates change.
+            const before = await tileFingerprints(cells, selected);
             for (const index of selected) {
                 await cells.nth(index).click({ timeout: 2000 });
-                await rememberClickedTile(cells, index, seenTiles);
+                await rememberClickedTile(cells, index, seenTiles, before.get(index));
             }
             totalSelections += selected.length;
             if (!selected.length) break;
-            await page.waitForTimeout(600);
+            // Dynamic 3x3 challenges replace selected tiles. Static and 4x4
+            // challenges do not, so stop sweeping once no replacement occurs.
+            if (!dynamic || !await waitForTileReplacement(page, cells, before, deadline)) break;
         }
         logs.push(`Local ${captchaType} grid round ${round + 1}: selected ${totalSelections} cells for "${prompt}"`);
+        const signature = await challengeSignature(frame, adapter);
         await frame.locator(totalSelections ? adapter.submit : adapter.noMatch).first().click({ timeout: 2000 });
-        const token = await waitForToken(page, captchaType, Math.min(2500, Math.max(0, deadline - Date.now())));
-        if (token) return token;
-        await page.waitForTimeout(350);
+        const result = await waitForSubmission(page, adapter, captchaType, signature, deadline, waitForToken);
+        if (result.token) return result.token;
+        if (!result.transitioned) await page.waitForTimeout(Math.min(350, Math.max(0, deadline - Date.now())));
     }
     return null;
 }
 
-module.exports = { PROVIDERS, normalizePrompt, normalizeModelLabel, normalizeBox, pngDimensions, mapDetectionsToCells, classifyGrid, rememberClickedTile, visibleText, solveImageGrid };
+module.exports = { PROVIDERS, normalizePrompt, normalizeModelLabel, normalizeBox, pngDimensions, mapDetectionsToCells, classifyGrid, rememberClickedTile, visibleText, tileFingerprint, tileFingerprints, waitForTileReplacement, challengeSignature, waitForSubmission, solveImageGrid };

package/src/captcha-local-solver.js

@@ -14,8 +14,8 @@ const WIDGET_INTERACTIONS = Object.freeze({
         selectors: ['#recaptcha-anchor', '[role="checkbox"]']
     }),
     hcaptcha: Object.freeze({
-        framePatterns: ['hcaptcha.com/captcha', 'newassets.hcaptcha.com/captcha'],
-        selectors: ['#checkbox', '[role="checkbox"]', 'input[type="checkbox"]', 'label']
+        framePatterns: ['hcaptcha.com', 'hcaptcha.html', 'hcaptcha-checkbox.html', 'frame=checkbox'],
+        selectors: ['#checkbox', '.check', '#anchor', '[role="checkbox"]', 'input[type="checkbox"]', 'label']
     }),
     turnstile: Object.freeze({
         framePatterns: ['challenges.cloudflare.com'],
@@ -23,6 +23,11 @@ const WIDGET_INTERACTIONS = Object.freeze({
     })
 });
 
+function frameMatches(frame, patterns) {
+    const url = String(frame?.url?.() || '').toLowerCase();
+    return patterns.some((pattern) => url.includes(pattern));
+}
+
 async function readToken(page, captchaType) {
     return page.evaluate(({ type, selectors }) => {
         for (const selector of selectors[type] || []) {
@@ -63,7 +68,7 @@ async function waitForTokenOrChallenge(page, captchaType, timeout) {
         if (token) return token;
         if (adapter) {
             for (const frame of page.frames?.() || []) {
-                if (!adapter.framePatterns.some((pattern) => frame.url().includes(pattern))) continue;
+                if (!frameMatches(frame, adapter.framePatterns)) continue;
                 if (await frame.locator(adapter.grid).first().isVisible({ timeout: 100 }).catch(() => false)) return null;
             }
         }
@@ -80,8 +85,7 @@ async function clickCheckbox(page, captchaType, timeout = 10_000) {
 
     do {
         for (const frame of page.frames?.() || []) {
-            const frameUrl = String(frame.url?.() || '');
-            if (!interaction.framePatterns.some((pattern) => frameUrl.includes(pattern))) continue;
+            if (!frameMatches(frame, interaction.framePatterns)) continue;
 
             for (const selector of interaction.selectors) {
                 const matches = frame.locator(selector);
@@ -112,13 +116,17 @@ async function clickCheckbox(page, captchaType, timeout = 10_000) {
 async function executeHcaptchaWidget(page) {
     return page.evaluate(() => {
         if (typeof globalThis.hcaptcha?.execute !== 'function') return false;
-        try {
-            const pending = globalThis.hcaptcha.execute();
-            if (pending && typeof pending.catch === 'function') pending.catch(() => {});
-            return true;
-        } catch {
-            return false;
+        const ids = [...document.querySelectorAll('[data-hcaptcha-widget-id]')]
+            .map((element) => element.getAttribute('data-hcaptcha-widget-id'))
+            .filter(Boolean);
+        for (const id of [...new Set([...ids, null])]) {
+            try {
+                const pending = id === null ? globalThis.hcaptcha.execute() : globalThis.hcaptcha.execute(id);
+                if (pending && typeof pending.catch === 'function') pending.catch(() => {});
+                return true;
+            } catch { /* try the default/next widget */ }
         }
+        return false;
     }).catch(() => false);
 }
 
@@ -133,7 +141,10 @@ async function solveLocalCaptcha(page, { captchaType, timeout = 60_000, logs = [
         : null;
     let token = await readToken(page, captchaType);
     if (!token) {
-        const clickTimeout = Math.min(10_000, Math.max(0, deadline - Date.now()));
+        // Invisible hCaptcha has no checkbox; do not spend ten seconds looking
+        // for one before invoking its documented execute path.
+        const interactionTimeout = captchaType === 'hcaptcha' ? 2500 : 10_000;
+        const clickTimeout = Math.min(interactionTimeout, Math.max(0, deadline - Date.now()));
         const clicked = await clickCheckbox(page, captchaType, clickTimeout)
             .catch((error) => {
                 logs.push(`Local ${captchaType} checkbox click failed: ${error.message}`);
@@ -159,7 +170,7 @@ async function solveLocalCaptcha(page, { captchaType, timeout = 60_000, logs = [
         let challengeVisible = false;
         while (!challengeVisible && Date.now() < frameDeadline) {
             for (const frame of page.frames?.() || []) {
-                if (!adapter.framePatterns.some((pattern) => frame.url().includes(pattern))) continue;
+                if (!frameMatches(frame, adapter.framePatterns)) continue;
                 challengeVisible = await frame.locator(adapter.grid).first().isVisible({ timeout: 100 }).catch(() => false);
                 if (challengeVisible) break;
             }
@@ -185,4 +196,4 @@ async function solveLocalCaptcha(page, { captchaType, timeout = 60_000, logs = [
     };
 }
 
-module.exports = { TOKEN_SELECTORS, WIDGET_INTERACTIONS, readToken, waitForToken, waitForTokenOrChallenge, clickCheckbox, executeHcaptchaWidget, solveLocalCaptcha };
+module.exports = { TOKEN_SELECTORS, WIDGET_INTERACTIONS, frameMatches, readToken, waitForToken, waitForTokenOrChallenge, clickCheckbox, executeHcaptchaWidget, solveLocalCaptcha };