Skip to content

feat(solvers): add Proof-of-Work (Altcha, Friendly Captcha) and Wasm challenge support - #122

Open
nklowns wants to merge 3 commits into
germondai:devfrom
nklowns:feat/pow-solvers
Open

feat(solvers): add Proof-of-Work (Altcha, Friendly Captcha) and Wasm challenge support#122
nklowns wants to merge 3 commits into
germondai:devfrom
nklowns:feat/pow-solvers

Conversation

@nklowns

@nklowns nklowns commented Sep 7, 2026

Copy link
Copy Markdown

Summary

Adds Proof-of-Work (PoW) and WebAssembly challenge handling to TRAWL. Provides in-page solvers for Altcha (SHA-256 PoW) and Friendly Captcha (v1 and v2 client puzzle) widgets, along with detection and dedicated waiting for PoW gates and WebAssembly interstitials (hasPowChallenge, waitForPowResolution).

Linked issues

Closes #121

Type of change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing behavior to change)
  • Documentation only

Checklist

  • I opened or commented on an issue before starting this PR (non-trivial changes only)
  • I ran bun run check and it passes locally
  • I added or updated tests for the behavior change (if applicable)
  • I updated CHANGELOG.md under ## [Unreleased] for user-visible changes
  • I read CONTRIBUTING.md and CODE_OF_CONDUCT.md

AGPL notice

By submitting this PR, I confirm my contribution is my own work and I agree to license it under AGPL-3.0.

…challenge support

- Implement in-page solver for Altcha SHA-256 Proof-of-Work widgets
- Implement in-page solver for Friendly Captcha (v1 and v2) client puzzle widgets
- Add PoW challenge detection and wall classification in utils/detect.ts
- Add dedicated waiter for PoW gates and WebAssembly interstitials in utils/powWait.ts
- Integrate with challengeRouter and solvePageCaptchas
- Add unit tests for detection, solving, routing, and waiters
- Update CHANGELOG.md under Unreleased

Resolves germondai#121
@nklowns
nklowns requested a review from germondai as a code owner September 7, 2026 21:46
@nklowns

nklowns commented Sep 7, 2026

Copy link
Copy Markdown
Author

Verification & Implementation Notes

  • Offline test coverage: 16 unit tests covering detection, challenge routing, solver execution, and Tier 1 escalation in packages/tiers/tests/powSolvers.test.ts and packages/tiers/tests/challengeRouter.test.ts. All test suites run completely offline using fixtures and mocked DOM states, preserving CI hermeticity without external network calls.
  • Verification Gate: Verified locally with bun run verify (Biome check, TypeScript typecheck across all 5 workspaces, all 391 monorepo tests passing, plus Nuxt web and VitePress documentation production builds).
  • Multi-Engine & Live Validation:
    • Tested live against the official Friendly Captcha v2 playground (developer.friendlycaptcha.com/playground) with both Chromium (Patchright) and Camoufox (Firefox-based).
    • Uses resilient page.frameLocator(...) with polling retry to handle out-of-process iframes under Firefox Fission cleanly.
    • Successfully clicked the widget, triggered the client-side Wasm/Web Worker PoW puzzle, and retrieved the verified signed 6KB solution token (AQQA.1_MUR...) within 5–9 seconds.
    • Altcha solver supports both open and closed Shadow DOM trees with native locator piercing.
  • Tier 1 Escalation: Static HTTP requests encountering PoW challenge shells or X-PoW-Challenge headers are properly escalated to status: "needs-js", allowing browser tiers to solve the challenge instead of misreporting an incomplete shell as a successful scrape.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[feat] Support Proof-of-Work (PoW) challenges (Altcha, Friendly Captcha, and Wasm interstitials)

1 participant