Captcha Session Handoff Design

Goal

Replace the blind webbrowser.open() + Enter retry with an observable browser handoff. A user completes the official challenge in a visible browser; the CLI waits for the official verification request to succeed, synchronizes cookies, and only then retries the original API request.

Scope

Included:

Open the HTTPS error_url in the normal system browser by default.
Observe kSecretApiVerify and extract a masked captchaToken for diagnostics.
Observe /rest/wd/captcha/verify and require a successful JSON result.
Copy browser cookies into the current requests.Session.
Preserve the current device profile, signed request body, and retry limits.
Fall back to the existing manual browser flow when Playwright is unavailable.

Excluded:

Image recognition, slider movement, trajectory generation, or fingerprint fabrication.
Replaying captured captcha tokens.
Treating a page close or terminal Enter as successful verification.

Architecture

core/captcha_assist.py owns the optional Playwright observation details and exposes one public operation returning a structured result. The CLI defaults to the regular system browser because Playwright-launched Edge exposes navigator.webdriver=true; msedge/chrome remain explicit diagnostic modes. Pure helpers parse response payloads and synchronize cookies so they can be tested without launching a browser.

Data Flow

705 error_url
  -> visible Edge page
  -> user completes official challenge
  -> observe kSecretApiVerify / captchaToken
  -> observe /rest/wd/captcha/verify result=1
  -> copy browser cookies to requests.Session
  -> retry the unchanged checker or mobileVerifyCode request

Error Handling

Reject non-HTTPS challenge URLs before browser launch.
Report missing Playwright separately from browser launch errors.
Stop on timeout, page close, malformed verification JSON, or non-success verification response.
Never print the full captcha token unless the existing secret-display option is explicitly enabled.

Testing

Unit-test recursive token extraction and verification-result recognition.
Unit-test browser-cookie transfer into a requests-compatible jar.
Unit-test that CLI retries after a verified handoff and does not retry after a failed handoff.
Run the focused SMS login tests and Python compilation checks.

2.4 KiB Raw Blame History