ZMediumToMarkdown 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef6ecd9a875dbef00977b254ceb317ec946c67003573a607e3a81662b91a76db
-  data.tar.gz: 9b4e3e21b0e3b08f6effdb4b2339f112dc53c1f5acae7655dea28ed23cbe78fa
+  metadata.gz: 1e19605bba5d079fa1086c14dfb33c7d33f36da86b46c6c6c97affc960521d26
+  data.tar.gz: 96e13a36f2573d2dae057ee7a318ad66d9d09dc69990deff5bf5033a72032f8c
 SHA512:
-  metadata.gz: e746fef4d6506fbb3894d3b5afd6dbfeb2a2850bebf4839c562482b397566b01e97866bde41e734e8c3e8824612f263cea21984025c60a1761c26623dd0501e7
-  data.tar.gz: bc4625d560ae67f278335eda453dcaf3ee511318af072a147a4c56ac0386c63f37ef049e77b37e8cdba672a386a7d915815f7dbbda5e1bbdc5488fdb091796d4
+  metadata.gz: 81e76d2686c7f06976ea9fdcb09243b75e5f628669e3c405b27a636705d6a54862f264c569bc4e33bcf571d3ba6696ed578b20a45350ea81fb993b605d76e860
+  data.tar.gz: 34d756095ba13548c551da107d9e4903b51d094087ce8ac71ed140f52adf0e3a852afbe35bae15b27c09ed08cafb4df91fc121bdf7e262b123e989b3053af8bb

data/lib/CLI.rb

@@ -5,6 +5,8 @@ require 'ZMediumFetcher'
 require 'Helper'
 require 'PathPolicy'
 require 'Request'
+require 'CookieCache'
+require 'ChromeAuth'
 
 # All CLI-side concerns for the `ZMediumToMarkdown` executable. Pulled out
 # of bin/ so it can be exercised by unit tests without spawning processes.
@@ -21,7 +23,7 @@ module CLI
         argv << '-h' if argv.empty?
 
         options = parseArgs(argv, errput: errput)
-        loadCookiesFromEnv!
+        loadCookies!
         warnAboutMissingSetup(options, errput: errput)
         run(options, cwd, output: output, errput: errput)
     end
@@ -39,6 +41,14 @@ module CLI
                 $cookies['uid'] = v
             end
 
+            opts.on('--cookie_cf_clearance VALUE', 'Cloudflare cf_clearance cookie value (or set $MEDIUM_COOKIE_CF_CLEARANCE)') do |v|
+                $cookies['cf_clearance'] = v
+            end
+
+            opts.on('--cookie_cfuvid VALUE', 'Cloudflare _cfuvid cookie value (or set $MEDIUM_COOKIE_CFUVID)') do |v|
+                $cookies['_cfuvid'] = v
+            end
+
             opts.on('-x', '--medium_host URL', 'Cloudflare Worker proxy URL for Medium GraphQL (or set $MEDIUM_HOST). Strongly recommended for CI / bulk runs — see the wiki setup guide.') do |v|
                 ENV['MEDIUM_HOST'] = v
             end
@@ -95,6 +105,15 @@ module CLI
                 options[:version] = true
             end
 
+            opts.on('--non-interactive', 'Never prompt or open a browser. CI runners auto-detect this; use the flag to force the same behavior on a TTY.') do
+                options[:nonInteractive] = true
+                ENV['MEDIUM_NO_AUTO_BROWSER'] = '1'
+            end
+
+            opts.on('--auth', 'Open Chrome to sign in, capture sid / uid / cf_clearance / _cfuvid into the encrypted cookie cache, and exit. Run once before bulk / scheduled jobs to seed the cache.') do
+                options[:auth] = true
+            end
+
             opts.on('-h', '--help', 'Show this help message') do
                 options[:help] = opts.to_s
             end
@@ -104,9 +123,31 @@ module CLI
         options
     end
 
+    # Cookie precedence (highest → lowest):
+    #   1. CLI flags          (already written to $cookies in parseArgs)
+    #   2. Env vars           (MEDIUM_COOKIE_*)
+    #   3. On-disk cache      (~/.config/ZMediumToMarkdown/cookies.json)
+    # Each layer only fills slots the higher layer left empty.
+    def loadCookies!
+        loadCookiesFromEnv!
+        loadCookiesFromCache!
+    end
+
     def loadCookiesFromEnv!
         $cookies['sid'] = ENV['MEDIUM_COOKIE_SID'] if cookieMissing?('sid') && !ENV['MEDIUM_COOKIE_SID'].to_s.empty?
         $cookies['uid'] = ENV['MEDIUM_COOKIE_UID'] if cookieMissing?('uid') && !ENV['MEDIUM_COOKIE_UID'].to_s.empty?
+        $cookies['cf_clearance'] = ENV['MEDIUM_COOKIE_CF_CLEARANCE'] if cookieMissing?('cf_clearance') && !ENV['MEDIUM_COOKIE_CF_CLEARANCE'].to_s.empty?
+        $cookies['_cfuvid'] = ENV['MEDIUM_COOKIE_CFUVID'] if cookieMissing?('_cfuvid') && !ENV['MEDIUM_COOKIE_CFUVID'].to_s.empty?
+    end
+
+    def loadCookiesFromCache!
+        cached = CookieCache.load
+        return if cached.empty?
+        ChromeAuth::TARGET_COOKIES.each do |name|
+            value = cached[name]
+            next if value.to_s.empty?
+            $cookies[name] = value if cookieMissing?(name)
+        end
     end
 
     def cookieMissing?(name)
@@ -131,6 +172,7 @@ module CLI
         !host.empty? && host != DEFAULT_MIRO_MEDIUM_HOST
     end
 
+
     # Only warn when the invocation will actually hit Medium — skip for
     # --version, --clean, --help, --new.
     def warnAboutMissingSetup(options, errput: $stderr)
@@ -150,57 +192,16 @@ module CLI
         !options[:postURL].nil? || !options[:username].nil?
     end
 
-    # Builds the dynamic setup-warning banner. Header lists exactly which
-    # of (cookies, GraphQL proxy, image proxy) is missing so the user can
-    # act; body is static guidance covering empirical limits, scenarios,
-    # and how to pass each value via flag or env.
+    # One-line warning. The wiki has the actual setup steps; we just
+    # nudge the user toward it instead of dumping a wall of guidance.
     def buildSetupBanner(missingCookies:, missingProxy:, missingImageProxy:)
-        lines = []
-        lines << '──────────────────────────────────────────────────────────────────────'
-        lines << '⚠  Setup notice — your run will work, but reliability is limited.'
-        lines << ''
-        lines << "What's missing:"
-        lines << '  • Medium login cookies (sid / uid).' if missingCookies
-        lines << '  • Cloudflare Worker proxy for Medium GraphQL (MEDIUM_HOST not set or still default).' if missingProxy
-        lines << '  • Cloudflare Worker proxy for image CDN (MIRO_MEDIUM_HOST not set or still default; optional companion).' if missingImageProxy
-        lines << ''
-        lines << <<~BODY.chomp
-          Empirical limits without setup:
-            • Without cookies         : Cloudflare blocks after ~10 posts.
-            • Without Worker proxy    : Cloudflare blocks after ~25 posts
-                                        when running from CI / datacenter IPs.
-            • Paywalled posts         : cookies are REQUIRED for full content;
-                                        without them you only get the preview.
-
-          Recommended setup:
-            • CI / CD (GitHub Actions, cloud runners):
-                STRONGLY recommend BOTH cookies AND a Cloudflare Worker proxy.
-            • Local machine:
-                Cookies recommended for paywalled posts. If a Cloudflare
-                challenge appears, the tool will automatically open
-                https://medium.com in your browser and prompt you to retry
-                once you've cleared it. Set MEDIUM_NO_AUTO_BROWSER=1 to
-                opt out and just fail fast.
-
-          Pass cookies via env (preferred — keeps secrets out of shell history):
-            MEDIUM_COOKIE_SID=... MEDIUM_COOKIE_UID=... ZMediumToMarkdown -p URL
-
-          Or via flags (fine for one-off local runs):
-            ZMediumToMarkdown -p URL -s YOUR_SID -d YOUR_UID
-
-          Pass Cloudflare Worker proxy URL(s):
-            ZMediumToMarkdown -p URL \\
-              -x https://YOUR-WORKER.workers.dev/_/graphql \\
-              --miro_medium_host https://YOUR-IMAGE-WORKER.workers.dev
-            # or via env:
-            #   MEDIUM_HOST=https://YOUR-WORKER.workers.dev/_/graphql
-            #   MIRO_MEDIUM_HOST=https://YOUR-IMAGE-WORKER.workers.dev
-
-          Full setup guide (cookies + Cloudflare Worker proxy):
-            #{COOKIE_SETUP_URL}
-          ──────────────────────────────────────────────────────────────────────
-        BODY
-        lines.join("\n")
+        missing = []
+        missing << 'Medium cookies (sid / uid)' if missingCookies
+        missing << 'Cloudflare Worker proxy (MEDIUM_HOST)' if missingProxy
+        missing << 'Cloudflare image proxy (MIRO_MEDIUM_HOST)' if missingImageProxy
+        return '' if missing.empty?
+
+        "⚠  Missing #{missing.join(' / ')}. Medium / Cloudflare may block the run. Setup guide: #{COOKIE_SETUP_URL}"
     end
 
     def run(options, cwd, output: $stdout, errput: $stderr)
@@ -234,6 +235,11 @@ module CLI
             return
         end
 
+        if options[:auth]
+            runAuth(errput: errput)
+            return
+        end
+
         # --stdout / --list path: render to the given output stream, skip
         # all filesystem writes and asset downloads. Progress goes to errput
         # so stdout stays pure markdown / NDJSON for embedding callers.
@@ -278,6 +284,32 @@ module CLI
         Helper.printNewVersionMessageIfExists()
     end
 
+    # `--auth` entry point: drive the Chrome login flow on demand so users
+    # can seed the cookie cache before kicking off a bulk / CI job. Errors
+    # are surfaced to errput; we never raise — `--auth` is best-effort
+    # setup, not a critical path.
+    def runAuth(errput: $stderr)
+        unless ChromeAuth.available?
+            errput.puts <<~MSG
+              ⚠  Chrome was not detected, so --auth can't run the auto-login flow.
+                 Install Google Chrome (or any Chromium-based browser ferrum can
+                 detect), or extract sid / uid manually — see:
+                 #{COOKIE_SETUP_URL}
+            MSG
+            return
+        end
+
+        cookies = ChromeAuth.login!(errput: errput)
+        if cookies.empty?
+            errput.puts '⚠  No cookies were captured. Make sure you finished signing in on a medium.com page before pressing Enter.'
+            return
+        end
+        cookies.each { |k, v| $cookies[k] = v unless v.to_s.empty? }
+        errput.puts "✅ Captured #{cookies.keys.join(' / ')} → #{CookieCache.path}"
+    rescue StandardError => e
+        errput.puts "(Auto-login failed: #{e.class}: #{e.message})"
+    end
+
     # Jekyll mode writes into the cwd (so files land in `_posts/...` and
     # `assets/...` of an existing Jekyll site). Plain mode nests under
     # `Output/` to keep the user's cwd tidy.

data/lib/ChromeAuth.rb

@@ -0,0 +1,163 @@
+require 'CookieCache'
+
+# Drive a visible Chrome (via ferrum / CDP) to let the user sign into Medium
+# in a real browser, then read sid/uid/cf_clearance/_cfuvid back out of the
+# session. Used both for first-time setup (no cookies on disk) and as the
+# Cloudflare-block recovery flow (cf_clearance refresh).
+#
+# "Headless" in the user's spec is a misnomer — login is interactive, so we
+# launch with headless:false and rely on the user to complete the login
+# in the visible window before pressing Enter.
+module ChromeAuth
+    TARGET_COOKIES = %w[sid uid cf_clearance _cfuvid].freeze
+    LOGIN_URL      = 'https://medium.com/m/signin'.freeze
+    REFRESH_URL    = 'https://medium.com'.freeze
+
+    @@session = nil
+
+    module_function
+
+    # True iff ferrum loads AND a Chrome binary is detectable. Anything
+    # else returns false so the caller can fall back to the legacy
+    # default-browser flow without aborting.
+    def available?
+        require 'ferrum'
+        path = Ferrum::Browser::Options::Chrome.options.detect_path
+        !path.nil? && !path.empty?
+    rescue LoadError, StandardError
+        false
+    end
+
+    # ---- Single-shot CLI flow ---------------------------------------
+    # Open Chrome at openURL, wait for the user to press Enter, then
+    # collect the four target cookies. Returns hash { 'sid' => '...', ... }
+    # — keys missing from the browser are simply omitted, so callers must
+    # check what came back rather than assume completeness.
+    #
+    # Raises StandardError on browser launch / navigation failure; callers
+    # are expected to rescue and degrade gracefully.
+    def login!(errput: $stderr, input: $stdin, openURL: LOGIN_URL)
+        startSession!(openURL: openURL)
+        promptUser(errput, input, openURL)
+        finishSession!
+    rescue StandardError
+        cancelSession!
+        raise
+    end
+
+    # ---- Split flow for MCP / other long-lived hosts ----------------
+    # `startSession!` / `finishSession!` / `cancelSession!` let a caller
+    # spawn the browser in one tool call and harvest cookies in another,
+    # using the host process (e.g. an MCP server) as the place that
+    # holds the still-open browser between calls.
+    #
+    # Lifecycle:
+    #   startSession!  → opens browser, returns immediately. If a session
+    #                    is already alive, that one is force-cancelled
+    #                    first so a stale browser can't strand cookies.
+    #   finishSession! → reads cookies from the live browser, writes
+    #                    cache, quits browser, clears session, returns
+    #                    the cookies hash.
+    #   cancelSession! → quit + clear; idempotent.
+    #
+    # Not thread-safe: assumes a single MCP request handler at a time.
+    def startSession!(openURL: LOGIN_URL)
+        cancelSession! if sessionActive?
+        browser = buildBrowser
+        browser.go_to(openURL)
+        @@session = { browser: browser, openURL: openURL, startedAt: Time.now }
+        { ok: true, openURL: openURL }
+    rescue StandardError
+        # If go_to or anything else blew up, make sure we don't leave a
+        # half-built browser around with no handle.
+        begin
+            browser&.quit
+        rescue StandardError
+            # ignore
+        end
+        @@session = nil
+        raise
+    end
+
+    def finishSession!
+        raise 'No active ChromeAuth session — call startSession! first.' unless sessionActive?
+        browser = @@session[:browser]
+        cookies = collectMediumCookies(browser)
+        CookieCache.save(CookieCache.load.merge(cookies)) if cookies.any?
+        cookies
+    ensure
+        cancelSession!
+    end
+
+    def cancelSession!
+        return false unless sessionActive?
+        browser = @@session[:browser]
+        @@session = nil
+        begin
+            browser&.quit
+        rescue StandardError
+            # ignore: best-effort shutdown
+        end
+        true
+    end
+
+    def sessionActive?
+        !@@session.nil?
+    end
+
+    # Factory split out so tests can stub it. Tweaking ferrum options
+    # globally (window size, timeouts) belongs here too.
+    def buildBrowser
+        require 'ferrum'
+        Ferrum::Browser.new(
+            headless: false,
+            window_size: [1280, 900],
+            timeout: 60,
+            process_timeout: 30
+        )
+    end
+
+    # Filter the browser's cookie jar down to medium.com cookies whose
+    # name is one of TARGET_COOKIES. We accept both .medium.com and
+    # medium.com because Cloudflare sets _cfuvid on the apex while
+    # Medium tends to set sid/uid on the dot-prefixed domain.
+    def collectMediumCookies(browser)
+        result = {}
+        browser.cookies.each do |cookie|
+            next unless TARGET_COOKIES.include?(cookie.name)
+            next unless mediumDomain?(cookie.domain)
+            result[cookie.name] = cookie.value
+        end
+        result
+    rescue StandardError
+        {}
+    end
+
+    def mediumDomain?(domain)
+        return false if domain.nil?
+        normalized = domain.start_with?('.') ? domain[1..] : domain
+        normalized == 'medium.com' || normalized.end_with?('.medium.com')
+    end
+
+    def promptUser(errput, input, url)
+        errput.puts <<~MSG
+
+          ──────────────────────────────────────────────────────────────────────
+          🔐 Sign into Medium in the Chrome window that just opened.
+
+          Steps:
+            1. Complete login (and any Cloudflare challenge) at #{url}.
+            2. Stay on a medium.com page once you're signed in.
+            3. Come back here and press Enter — we'll read sid / uid /
+               cf_clearance / _cfuvid out of the browser and cache them at
+               #{CookieCache.path}.
+
+          (Press Ctrl-D to abort and fall back to manual setup.)
+          ──────────────────────────────────────────────────────────────────────
+        MSG
+        errput.print 'Press Enter when signed in… '
+        line = input.gets
+        errput.puts
+        line
+    end
+end

data/lib/CookieCache.rb

@@ -0,0 +1,93 @@
+require 'json'
+require 'fileutils'
+require 'openssl'
+
+# On-disk cache for Medium / Cloudflare cookies captured by ChromeAuth.
+# Stored at ~/.zmediumtomarkdown so subsequent runs can reuse sid/uid
+# (long-lived) and ride out a still-valid cf_clearance/_cfuvid without
+# prompting again.
+#
+# Encrypted at rest with AES-256-GCM using a fixed key shipped with the
+# gem. The key is constant on purpose — this is *obfuscation against
+# casual file-system snoops*, not protection from an attacker who has
+# the gem source. The file is also written 0600.
+#
+# On-disk layout (binary):
+#   bytes 0..11   : 12-byte IV     (random per write)
+#   bytes 12..27  : 16-byte tag    (GCM auth tag)
+#   bytes 28..    : ciphertext
+#
+# The path can be overridden with ZMEDIUM_COOKIE_CACHE_PATH (used by tests
+# and power users who want the cache in a different location).
+module CookieCache
+    PATH_ENV = 'ZMEDIUM_COOKIE_CACHE_PATH'.freeze
+    DEFAULT_BASENAME = '.zmediumtomarkdown'.freeze
+    CIPHER  = 'aes-256-gcm'.freeze
+    SECRET  = 'r3n2wJAX8o944MqFVZPwirjUGZ9A7mII'.freeze  # 32 bytes → AES-256
+    IV_LEN  = 12
+    TAG_LEN = 16
+
+    module_function
+
+    def path
+        override = ENV[PATH_ENV].to_s
+        return override unless override.empty?
+        File.join(Dir.home, DEFAULT_BASENAME)
+    end
+
+    # Returns hash of cached cookies. Missing file or unreadable / corrupt
+    # blob (wrong key, truncated, tampered) returns {} — never raises, so
+    # the caller can treat the cache as best-effort.
+    def load
+        return {} unless File.exist?(path)
+        plaintext = decrypt(File.binread(path))
+        parsed = JSON.parse(plaintext)
+        parsed.is_a?(Hash) ? parsed : {}
+    rescue StandardError
+        {}
+    end
+
+    # Atomic write: encrypt the JSON blob, write to a sibling tmp file at
+    # 0600, rename. Best-effort: any IO/encryption error is swallowed
+    # (cache is convenience, not source of truth — losing a write should
+    # not abort the run).
+    def save(hash)
+        return unless hash.is_a?(Hash) && !hash.empty?
+        FileUtils.mkdir_p(File.dirname(path))
+        tmp = "#{path}.tmp.#{Process.pid}"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC | File::BINARY, 0o600) do |f|
+            f.write(encrypt(JSON.generate(hash)))
+        end
+        File.rename(tmp, path)
+    rescue StandardError
+        File.unlink(tmp) if defined?(tmp) && tmp && File.exist?(tmp)
+    end
+
+    def clear
+        File.unlink(path) if File.exist?(path)
+    rescue Errno::ENOENT
+        # already gone
+    end
+
+    def encrypt(plaintext)
+        cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+        cipher.key = SECRET
+        iv = cipher.random_iv  # 12 bytes
+        cipher.auth_data = ''
+        ct = cipher.update(plaintext) + cipher.final
+        iv + cipher.auth_tag + ct
+    end
+
+    def decrypt(blob)
+        raise 'cache blob too short' if blob.nil? || blob.bytesize < IV_LEN + TAG_LEN
+        iv  = blob.byteslice(0, IV_LEN)
+        tag = blob.byteslice(IV_LEN, TAG_LEN)
+        ct  = blob.byteslice(IV_LEN + TAG_LEN, blob.bytesize - IV_LEN - TAG_LEN)
+        cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+        cipher.key = SECRET
+        cipher.iv  = iv
+        cipher.auth_tag  = tag
+        cipher.auth_data = ''
+        cipher.update(ct) + cipher.final
+    end
+end

data/lib/Request.rb

@@ -1,5 +1,7 @@
 require 'net/http'
 require 'nokogiri'
+require 'ChromeAuth'
+require 'CookieCache'
 
 class Request
     # Raised when Medium's Cloudflare layer blocks the request (typically
@@ -27,20 +29,22 @@ class Request
               Pick the fix that matches where you're running:
 
                 • Local machine (your laptop / desktop):
-                    Open https://medium.com in a normal browser and complete
-                    the Cloudflare challenge ("I'm not a robot" / "Just a
-                    moment…"). Then re-run the script — your residential IP
-                    will be cleared for a while.
+                    Re-run on a TTY without --non-interactive to trigger
+                    the Chrome auto-login flow (captures sid / uid /
+                    cf_clearance / _cfuvid). Or open https://medium.com
+                    in a normal browser and clear the challenge by hand.
 
                 • CI / CD (GitHub Actions, cloud runners):
                     A human can't clear the challenge. Set up BOTH:
                       1. Medium login cookies (sid / uid) — pass via env
                          MEDIUM_COOKIE_SID and MEDIUM_COOKIE_UID, or via
-                         the -s / -d flags.
+                         the -s / -d flags. Optionally add cf_clearance
+                         / _cfuvid via MEDIUM_COOKIE_CF_CLEARANCE /
+                         MEDIUM_COOKIE_CFUVID for short-term unblocking.
                       2. A Cloudflare Worker proxy so requests originate
                          from inside Cloudflare's network instead of a
                          flagged datacenter IP. Point the tool at it via
-                         the MEDIUM_HOST env var.
+                         the MEDIUM_HOST env var. (Recommended.)
 
               Full step-by-step setup guide:
               https://github.com/ZhgChgLi/ZMediumToMarkdown/wiki/Setting-Up-Medium-Cookies-and-a-Cloudflare-Worker-Proxy
@@ -100,9 +104,42 @@ class Request
         end
 
         # Run the interactive recovery flow. Returns true if the user
-        # confirmed they cleared the challenge, false if they pressed Ctrl-D
+        # cleared the challenge (and, when Chrome is available, we
+        # successfully refreshed cookies); false if they pressed Ctrl-D
         # (EOF) or otherwise gave up.
+        #
+        # Two paths:
+        #   1. ChromeAuth available → drive Chrome via ferrum; on success
+        #      sid/uid/cf_clearance/_cfuvid land in $cookies and the cache.
+        #   2. Otherwise → legacy fallback: open default browser, ask the
+        #      user to clear the challenge by hand, retry without new cookies.
         def run(url, errput: $stderr, input: $stdin, autoOpen: true)
+            if ChromeAuth.available?
+                return runChromeFlow(url, errput: errput, input: input)
+            end
+
+            runDefaultBrowserFlow(url, errput: errput, input: input, autoOpen: autoOpen)
+        end
+
+        def runChromeFlow(url, errput:, input:)
+            errput.puts <<~MSG
+
+              ──────────────────────────────────────────────────────────────────────
+              ⚠  Cloudflare bot challenge detected at #{url}.
+                 Opening Chrome so you can clear it (and refresh login if needed).
+              ──────────────────────────────────────────────────────────────────────
+
+            MSG
+            cookies = ChromeAuth.login!(errput: errput, input: input,
+                                         openURL: ChromeAuth::REFRESH_URL)
+            cookies.each { |k, v| $cookies[k] = v unless v.to_s.empty? }
+            !cookies.empty?
+        rescue StandardError => e
+            errput.puts "(Chrome auto-recovery failed: #{e.class}: #{e.message}. Falling back to default browser.)"
+            runDefaultBrowserFlow(url, errput: errput, input: input, autoOpen: true)
+        end
+
+        def runDefaultBrowserFlow(url, errput:, input:, autoOpen:)
             errput.puts <<~MSG
 
               ──────────────────────────────────────────────────────────────────────
@@ -114,6 +151,7 @@ class Request
                 2. Complete the "Just a moment…" / CAPTCHA challenge there.
                 3. Come back here and press Enter to retry.
 
+              (Install Google Chrome to enable auto-cookie capture next time.)
               (To disable this prompt and just fail fast, set #{DISABLE_ENV_VAR}=1.)
               ──────────────────────────────────────────────────────────────────────
 
@@ -128,12 +166,10 @@ class Request
         end
     end
 
-    @@cloudflareInteractiveResolutionAttempted = false
-
-    # Test helper: reset the once-per-process recovery flag.
-    def self.resetCloudflareInteractiveResolution!
-        @@cloudflareInteractiveResolutionAttempted = false
-    end
+    # Cap how many times a single self.URL call chain can fall through
+    # the Cloudflare-recovery branch, so a user who keeps saying yes to
+    # the prompt while Medium keeps blocking can't loop forever.
+    CLOUDFLARE_RECOVERY_LIMIT = 5
 
     def self.URL(url, method = 'GET', data = nil, retryCount = 0)
         retryCount += 1
@@ -204,11 +240,13 @@ class Request
         end
 
         if cloudflareBlocked?(response)
-            # Once-per-process: if we're on an interactive TTY, ask the user
-            # to clear the challenge in a browser and retry. CI / non-TTY
-            # environments fall straight through to the raise below.
-            if !@@cloudflareInteractiveResolutionAttempted && InteractiveCloudflareRecovery.available?
-                @@cloudflareInteractiveResolutionAttempted = true
+            # On every Cloudflare block — even when cookies are already
+            # set — re-run the recovery flow on a TTY. ChromeAuth refreshes
+            # sid/uid/cf_clearance/_cfuvid into $cookies + the cache, so
+            # the next attempt usually succeeds. Bounded by retryCount so
+            # a degenerate loop (user keeps clearing, Medium keeps blocking)
+            # eventually surfaces the error. CI / non-TTY just raises.
+            if retryCount <= CLOUDFLARE_RECOVERY_LIMIT && InteractiveCloudflareRecovery.available?
                 if InteractiveCloudflareRecovery.run(url)
                     return self.URL(url, method, data, retryCount)
                 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ZMediumToMarkdown
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.3.0
 platform: ruby
 authors:
 - ZhgChgLi
 bindir: bin
 cert_chain: []
-date: 2026-05-05 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -77,6 +77,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
 description: ZMediumToMarkdown converts Medium posts into clean, portable Markdown.
   It can download a single post or every post from a Medium username, preserving headings,
   lists, blockquotes, code blocks, images, links, and common embeds such as GitHub
@@ -89,6 +103,8 @@ extra_rdoc_files: []
 files:
 - bin/ZMediumToMarkdown
 - lib/CLI.rb
+- lib/ChromeAuth.rb
+- lib/CookieCache.rb
 - lib/Helper.rb
 - lib/ImageDownloader.rb
 - lib/Models/Paragraph.rb