65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|