flaresolverr 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 Kiko Beats <josefrancisco.verdu@gmail.com> (kikobeats.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# flaresolverr
+
+<p align="center">
+  <br>
+  <img src="https://i.imgur.com/Mh13XWB.gif" alt="flaresolverr">
+  <br>
+</p>
+
+![Last version](https://img.shields.io/github/tag/kikobeats/flaresolverr.svg?style=flat-square)
+[![Coverage Status](https://img.shields.io/coveralls/kikobeats/flaresolverr.svg?style=flat-square)](https://coveralls.io/github/kikobeats/flaresolverr)
+[![NPM Status](https://img.shields.io/npm/dm/flaresolverr.svg?style=flat-square)](https://www.npmjs.org/package/flaresolverr)
+
+**NOTE:** more badges availables in [shields.io](https://shields.io/)
+
+> A Node.js port of FlareSolverr
+
+## Install
+
+```bash
+$ npm install flaresolverr --global
+```
+
+## CLI
+
+```bash
+$ flaresolverr --help
+
+  Generates regular expressions that match a set of strings.
+
+  Usage
+    $ flaresolverr [-gimuy] string1 string2 string3...
+
+  Examples
+    $ flaresolverr foobar foobaz foozap fooza
+    $ jq '.keywords' package.json | flaresolverr
+```
+
+## License
+
+**flaresolverr** © [Kiko Beats](https://kikobeats.com), released under the [MIT](https://github.com/kikobeats/flaresolverr/blob/master/LICENSE.md) License.<br>
+Authored and maintained by [Kiko Beats](https://kikobeats.com) with help from [contributors](https://github.com/kikobeats/flaresolverr/contributors).
+
+> [kikobeats.com](https://kikobeats.com) · GitHub [Kiko Beats](https://github.com/kikobeats) · Twitter [@kikobeats](https://twitter.com/kikobeats)

package/bin/help.txt

@@ -0,0 +1,13 @@
+Usage
+  $ flaresolverr <command>[options]
+
+Commands
+  --file Read the file
+
+Options
+  --wait  Wait for the app to exit
+
+Examples
+  $ npm-url # Open the current package if you are over package.json path.
+  $ npm-url json-future
+  $ npm-url json-future -- 'google chrome' --incognito

package/bin/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict'
+
+const pkg = require('../package.json')
+const mri = require('mri')
+
+require('update-notifier')({ pkg }).notify()
+
+const { _, ...flags } = mri(process.argv.slice(2), {
+  /* https://github.com/lukeed/mri#usage< */
+  default: {
+    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+  }
+})
+
+if (flags.help) {
+  console.log(require('fs').readFileSync('./help.txt', 'utf8'))
+  process.exit(0)
+}
+
+Promise.resolve(
+  require('flaresolverr')({
+    ...flags
+  })
+)
+  .then(() => {
+    process.exit(0)
+  })
+  .catch(error => {
+    console.error(error)
+    process.exit(1)
+  })

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "flaresolverr",
+  "description": "A Node.js port of FlareSolverr",
+  "homepage": "https://github.com/kikobeats/flaresolverr",
+  "version": "0.0.0",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./cli/index.js"
+  },
+  "bin": {
+    "flaresolverr": "bin/index.js"
+  },
+  "author": {
+    "email": "josefrancisco.verdu@gmail.com",
+    "name": "Kiko Beats",
+    "url": "https://kikobeats.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kikobeats/flaresolverr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kikobeats/flaresolverr/issues"
+  },
+  "keywords": [
+    "flaresolverr"
+  ],
+  "dependencies": {
+    "mri": "~1.2.0"
+  },
+  "devDependencies": {
+    "@browserless/test": "latest",
+    "@commitlint/cli": "latest",
+    "@commitlint/config-conventional": "latest",
+    "@ksmithut/prettier-standard": "latest",
+    "async-listen": "latest",
+    "ava": "latest",
+    "browserless": "latest",
+    "c8": "latest",
+    "finepack": "latest",
+    "git-authors-cli": "latest",
+    "github-generate-release": "latest",
+    "nano-staged": "latest",
+    "simple-git-hooks": "latest",
+    "standard": "latest",
+    "standard-markdown": "latest",
+    "standard-version": "latest"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "preferGlobal": true,
+  "license": "MIT",
+  "ava": {
+    "files": [
+      "test/**/*.js",
+      "!test/util.js"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ],
+    "rules": {
+      "body-max-line-length": [
+        0
+      ]
+    }
+  },
+  "nano-staged": {
+    "*.js": [
+      "prettier-standard",
+      "standard --fix"
+    ],
+    "*.md": [
+      "standard-markdown"
+    ],
+    "package.json": [
+      "finepack"
+    ]
+  },
+  "simple-git-hooks": {
+    "commit-msg": "npx commitlint --edit",
+    "pre-commit": "npx nano-staged"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
+    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
+    "lint": "standard-markdown README.md && standard",
+    "postrelease": "npm run release:tags && npm run release:github && npm publish",
+    "pretest": "npm run lint",
+    "release": "standard-version -a",
+    "release:github": "github-generate-release",
+    "release:tags": "git push --follow-tags origin HEAD:master",
+    "test": "c8 ava"
+  }
+}

package/src/constants.js

@@ -0,0 +1,87 @@
+'use strict'
+
+module.exports = {
+  /**
+   * CSS selectors for DOM elements that indicate a blocked request.
+   * These elements contain error codes and messages shown on block pages.
+   */
+  ACCESS_DENIED_SELECTORS: [
+    'div.cf-error-title span.cf-code-label span',
+    '#cf-error-details div.cf-error-overview h1'
+  ],
+
+  /**
+   * Page titles that indicate the request has been blocked entirely.
+   * Unlike challenges, blocks cannot be bypassed and require different handling.
+   */
+  ACCESS_DENIED_TITLES: ['Access denied', 'Attention Required! | Cloudflare'],
+
+  /**
+   * Cookie names that indicate a challenge bypass has been granted.
+   * - cf_clearance: Cloudflare's main bypass cookie
+   * - __ddg*: DDoS-Guard cookies
+   * - fl_pass*: FlareSolverr-specific cookies
+   */
+  CHALLENGE_COOKIE_PREFIXES: ['cf_clearance', '__ddg', 'fl_pass'],
+
+  /**
+   * CSS selectors for DOM elements that indicate an active challenge.
+   * These elements are present during the challenge verification process.
+   *
+   * - #cf-challenge-running: Main Cloudflare challenge container
+   * - .ray_id: Cloudflare Ray ID display (shown during challenges)
+   * - .attack-box: DDoS protection warning box
+   * - #cf-please-wait: "Please wait" message during verification
+   * - #challenge-spinner: Loading spinner during challenge processing
+   * - #trk_jschal_js: JavaScript challenge tracking element
+   * - #turnstile-wrapper: Cloudflare Turnstile CAPTCHA container
+   * - .lds-ring: Loading ring animation (common in challenge pages)
+   */
+  CHALLENGE_SELECTORS: [
+    '#cf-challenge-running',
+    '.ray_id',
+    '.attack-box',
+    '#cf-please-wait',
+    '#challenge-spinner',
+    '#trk_jschal_js',
+    '#turnstile-wrapper',
+    '.lds-ring'
+  ],
+
+  /**
+   * Page titles that indicate an active challenge is being presented.
+   * - "Just a moment..." - Cloudflare's standard challenge page title
+   * - "DDoS-Guard" - Alternative protection service
+   */
+  CHALLENGE_TITLES: ['Just a moment...', 'DDoS-Guard'],
+
+  /**
+   * Time to wait after navigation to ensure cookies are persisted.
+   * Cloudflare sets cookies asynchronously, so we need a small buffer.
+   */
+  COOKIE_PERSISTENCE_DELAY_MS: 500,
+
+  /**
+   * Default timeout for waiting on challenge resolution.
+   * If the challenge doesn't resolve within this time, we attempt manual verification.
+   */
+  DEFAULT_CHALLENGE_TIMEOUT_MS: 5000,
+
+  /**
+   * Default maximum number of attempts to solve a challenge.
+   * Each attempt includes waiting for auto-resolution and manual verification.
+   */
+  DEFAULT_MAX_ATTEMPTS: 10,
+
+  /**
+   * Short delay between keyboard actions during manual verification.
+   * Simulates human-like interaction timing.
+   */
+  KEYBOARD_ACTION_DELAY_MS: 100,
+
+  /**
+   * Time to wait after clicking the verify button.
+   * Allows the challenge to process the interaction.
+   */
+  POST_VERIFY_CLICK_DELAY_MS: 2000
+}

package/src/index.js

@@ -0,0 +1,308 @@
+'use strict'
+
+/**
+ * Port of FlareSolverr to browserless.
+ *
+ * FlareSolverr is a proxy server to bypass Cloudflare and DDoS-Guard protection.
+ * This module implements the core challenge-solving logic using Puppeteer.
+ *
+ * @see https://github.com/FlareSolverr/FlareSolverr
+ */
+
+const { setTimeout } = require('node:timers/promises')
+const debug = require('debug-logfmt')('flaresolverr')
+
+const { generatePostFormHtml, isChallengeCookie, parsePostData } = require('./util')
+
+const {
+  ACCESS_DENIED_SELECTORS,
+  ACCESS_DENIED_TITLES,
+  CHALLENGE_SELECTORS,
+  CHALLENGE_TITLES,
+  COOKIE_PERSISTENCE_DELAY_MS,
+  DEFAULT_CHALLENGE_TIMEOUT_MS,
+  DEFAULT_MAX_ATTEMPTS,
+  KEYBOARD_ACTION_DELAY_MS,
+  POST_VERIFY_CLICK_DELAY_MS
+} = require('./constants')
+
+/* =============================================================================
+ * DETECTION FUNCTIONS
+ * ============================================================================= */
+
+/**
+ * Checks if the current page is presenting a challenge page (e.g., Cloudflare or DDoS-Guard).
+ *
+ * Detection is performed in two phases:
+ * 1. Title matching: Fast check against known challenge page titles
+ * 2. Selector matching: DOM inspection for challenge-specific elements
+ *
+ * @param {import('puppeteer').Page} page - The Puppeteer page instance to check for challenges.
+ * @returns {Promise<boolean>} - Resolves to true if a challenge page is detected, otherwise false.
+ */
+const isChallenge = async page => {
+  // Phase 1: Check page title for known challenge indicators
+  const title = await page.title()
+  const matchedTitle = CHALLENGE_TITLES.find(challengeTitle => title.includes(challengeTitle))
+  if (matchedTitle) {
+    debug('isChallenge:title', { title, matchedTitle })
+    return true
+  }
+
+  // Phase 2: Check DOM for challenge-specific elements
+  for (const selector of CHALLENGE_SELECTORS) {
+    const element = await page.$(selector)
+    if (element) {
+      debug('isChallenge:selector', { selector })
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Checks if the current page is blocked by an access denied or Cloudflare block page.
+ *
+ * Block pages differ from challenges in that they cannot be bypassed.
+ * When detected, the calling code should fail fast rather than retry.
+ *
+ * @param {import('puppeteer').Page} page - The Puppeteer page instance to check for blocks.
+ * @returns {Promise<boolean>} - True if a block page is detected, otherwise false.
+ */
+const isBlock = async page => {
+  // Phase 1: Check page title for known block indicators
+  const title = await page.title()
+  const matchedTitle = ACCESS_DENIED_TITLES.find(blockTitle => title.includes(blockTitle))
+  if (matchedTitle) {
+    debug('isBlock:title', { title, matchedTitle })
+    return true
+  }
+
+  // Phase 2: Check DOM for block-specific elements
+  for (const selector of ACCESS_DENIED_SELECTORS) {
+    const element = await page.$(selector)
+    if (element) {
+      debug('isBlock:selector', { selector })
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Attempts to bypass Cloudflare and DDoS-Guard protection for a given URL.
+ *
+ * The bypass process works as follows:
+ * 1. Navigate to the target URL
+ * 2. Detect if a challenge is present
+ * 3. Wait for automatic challenge resolution (JavaScript-based)
+ * 4. If auto-resolution fails, attempt manual verification via keyboard simulation
+ * 5. Repeat until challenge is solved or max attempts reached
+ *
+ * @param {string} url - The URL to access.
+ * @param {Object} options - Configuration options.
+ * @param {number} [options.attempt=10] - Maximum number of challenge-solving attempts.
+ * @param {string} [options.method='GET'] - HTTP method (GET or POST).
+ * @param {Function} options.getBrowserless - Function that returns a browserless instance.
+ * @param {string} [options.postData] - URL-encoded POST data (required if method is POST).
+ * @param {number} [options.timeout=5000] - Timeout for challenge resolution in milliseconds.
+ * @param {boolean} [options.returnOnlyCookies] - If true, only return cookies without page content.
+ * @param {Array} [options.cookies] - Cookies to set before navigation.
+ * @returns {Promise<Object>} - The result object containing status, message, and solution.
+ */
+const flaresolverr = async (
+  url,
+  {
+    attempt: maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    method = 'GET',
+    getBrowserless,
+    postData,
+    timeout: challengeTimeout = DEFAULT_CHALLENGE_TIMEOUT_MS,
+    ...opts
+  } = {}
+) => {
+  const browserless = await getBrowserless()
+
+  const result = await browserless.withPage(
+    (page, goto) =>
+      async (url, { method, postData, cookies }) => {
+        let challengeDetected = false
+
+        /**
+         * Navigates to the target URL, handling both GET and POST requests.
+         * POST requests are handled by injecting a form and submitting it,
+         * which allows proper challenge handling on POST endpoints.
+         */
+        const navigate = async () => {
+          debug('navigate', { url, method, postData })
+
+          // Set cookies before navigation if provided
+          if (cookies && cookies.length > 0) {
+            const cookiesWithDomain = cookies.map(cookie => ({
+              ...cookie,
+              // If no URL or domain is specified, use the target URL
+              url: cookie.url || cookie.domain ? undefined : url
+            }))
+            debug('navigate:cookies', { count: cookiesWithDomain.length })
+            await page.setCookie(...cookiesWithDomain)
+          }
+
+          if (method === 'POST') {
+            debug('navigate:post')
+            const formFields = parsePostData(postData)
+            const formHtml = generatePostFormHtml(url, formFields)
+            await page.setContent(formHtml)
+          } else {
+            const timeout = opts.timeout || challengeTimeout
+            debug('navigate:get', { timeout, ...opts })
+            const { response, error } = await goto(page, {
+              url,
+              ...opts,
+              timeout
+            })
+
+            if (error) {
+              debug('navigate:get:error', { message: error.message, code: error.code })
+              throw error
+            }
+
+            debug('navigate:get:response', {
+              status: response ? response.status() : 'no response',
+              title: await page.title()
+            })
+          }
+
+          debug('navigate:finished')
+        }
+
+        await navigate()
+
+        // Wait for cookies to be persisted after navigation
+        await setTimeout(COOKIE_PERSISTENCE_DELAY_MS)
+
+        // Check for challenge cookies that indicate a challenge occurred
+        const initialCookies = await page.cookies()
+        const hasChallengeCookie = initialCookies.some(isChallengeCookie)
+
+        if (hasChallengeCookie) {
+          debug('challenge:detected:cookie')
+          challengeDetected = true
+        }
+
+        /**
+         * Attempts to manually verify the challenge using keyboard simulation.
+         * This mimics a user pressing Tab to focus the verify button, then Space to click it.
+         * Used when automatic JavaScript-based resolution fails.
+         */
+        const attemptManualVerification = async () => {
+          debug('manualVerification:attempt')
+
+          // Wait for the challenge UI to be ready
+          await setTimeout(challengeTimeout)
+
+          // Tab to focus the verify button
+          await page.keyboard.press('Tab')
+          await setTimeout(KEYBOARD_ACTION_DELAY_MS)
+
+          // Press Space to activate the button
+          await page.keyboard.press('Space')
+
+          // Wait for the verification to process
+          await setTimeout(POST_VERIFY_CLICK_DELAY_MS)
+
+          debug('manualVerification:finished')
+        }
+
+        // Fail fast if the page is blocked (not just challenged)
+        if (await isBlock(page)) {
+          debug('block:detected')
+          throw new Error('Cloudflare has blocked this request.')
+        }
+
+        // Start attempt counter based on whether we've already detected a challenge
+        let attemptCount = challengeDetected ? 1 : 0
+
+        // Challenge resolution loop
+        while ((await isChallenge(page)) && attemptCount < maxAttempts) {
+          attemptCount++
+          debug('challenge:attempt', { attempt: attemptCount, maxAttempts })
+
+          try {
+            debug('challenge:wait')
+
+            /**
+             * Wait for the challenge to resolve automatically.
+             * The challenge is considered resolved when:
+             * 1. The page title no longer matches any challenge titles
+             * 2. No challenge-specific DOM elements are present
+             */
+            await page.waitForFunction(
+              (titles, selectors) => {
+                const title = document.title
+                // Check if title still indicates a challenge
+                if (titles.some(challengeTitle => title.includes(challengeTitle))) {
+                  return false
+                }
+                // Check if any challenge elements are still present
+                for (const selector of selectors) {
+                  if (document.querySelector(selector)) {
+                    return false
+                  }
+                }
+                return true
+              },
+              { timeout: challengeTimeout },
+              CHALLENGE_TITLES,
+              CHALLENGE_SELECTORS
+            )
+
+            debug('challenge:solved:auto')
+            break
+          } catch (err) {
+            // Auto-resolution timed out, attempt manual verification
+            debug('challenge:retry', { message: err.message })
+            await attemptManualVerification()
+          }
+        }
+
+        if (attemptCount === 0) {
+          debug('challenge:not_detected')
+        } else if (attemptCount >= maxAttempts) {
+          debug('challenge:max_attempts_reached')
+        }
+
+        // Gather final page state
+        const [resolvedCookies, userAgent, content] = await Promise.all([
+          page.cookies(),
+          page.evaluate(() => navigator.userAgent),
+          page.content()
+        ])
+
+        debug('result:cookies', { names: resolvedCookies.map(c => c.name) })
+
+        const challengeWasSolved = attemptCount > 0
+
+        return {
+          status: 'ok',
+          message: challengeWasSolved ? 'Challenge solved!' : 'Challenge not detected!',
+          solution: {
+            url: page.url(),
+            status: 200,
+            cookies: resolvedCookies,
+            userAgent,
+            response: opts.returnOnlyCookies ? null : content,
+            headers: opts.returnOnlyCookies ? null : {}
+          }
+        }
+      }
+  )(url, { method, postData, ...opts })
+
+  return result
+}
+
+flaresolverr.isChallenge = isChallenge
+flaresolverr.isBlock = isBlock
+
+module.exports = flaresolverr

package/src/util.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const { CHALLENGE_COOKIE_PREFIXES } = require('./constants')
+
+/**
+ * Checks if a cookie indicates a challenge bypass has been granted.
+ *
+ * @param {Object} cookie - The cookie object to check.
+ * @param {string} cookie.name - The name of the cookie.
+ * @returns {boolean} - True if the cookie indicates a challenge bypass.
+ */
+const isChallengeCookie = cookie =>
+  CHALLENGE_COOKIE_PREFIXES.some(prefix => cookie.name === prefix || cookie.name.startsWith(prefix))
+
+/**
+ * Parses POST data string into an array of name-value pairs.
+ * Handles URL-encoded form data format.
+ *
+ * @param {string} postData - The POST data string (e.g., "key1=value1&key2=value2").
+ * @returns {Array<{name: string, value: string}>} - Array of decoded name-value pairs.
+ */
+const parsePostData = postData => {
+  const query = postData.startsWith('?') ? postData.substring(1) : postData
+  return query.split('&').map(pair => {
+    const [name, value] = pair.split('=')
+    return {
+      name: decodeURIComponent(name),
+      value: decodeURIComponent(value || '')
+    }
+  })
+}
+
+/**
+ * Generates an HTML form for POST request submission.
+ * This is used to submit POST requests through the browser context,
+ * which is necessary to properly handle challenges on POST endpoints.
+ *
+ * @param {string} url - The form action URL.
+ * @param {Array<{name: string, value: string}>} formFields - The form fields.
+ * @returns {string} - The complete HTML document string.
+ */
+const generatePostFormHtml = (url, formFields) => {
+  const hiddenInputs = formFields
+    .map(({ name, value }) => {
+      const escapedValue = value.replace(/"/g, '&quot;')
+      return `<input type="hidden" name="${name}" value="${escapedValue}">`
+    })
+    .join('')
+
+  return `
+    <!DOCTYPE html>
+    <html>
+    <body>
+      <form id="hackForm" action="${url}" method="POST">
+        ${hiddenInputs}
+      </form>
+      <script>document.getElementById('hackForm').submit();</script>
+    </body>
+    </html>
+  `
+}
+
+module.exports = {
+  generatePostFormHtml,
+  isChallengeCookie,
+  parsePostData
+}