Add ALTCHA support (v1.2.0) - #2
Merged
Merged
Conversation
ALTCHA is proof-of-work rather than recognition: the site issues a challenge and the client brute-forces a number that satisfies it. Solves are therefore deterministic and take milliseconds. `altcha($url, $options)` takes either `challenge_url`, which CapSkip fetches, or `challenge_json` with the document itself -- a JSON string, or an array that is serialized for you, since a form body would otherwise carry the string "Array". Sending both is allowed and the inline document wins, matching the server, which is deliberately more permissive here than 2Captcha's mutually-exclusive spelling. AsyncCapSkip inherits it, as it does every other solve method. The result exposes `token` (what the site's `altcha` form field expects, verbatim) and `number`, the counter that solved it, decoded from the base64 payload with base64_decode in strict mode so garbage is not silently accepted. `code` keeps the same raw string so callers porting from another solver's API keep working. Unlike GeeTest and reCAPTCHA this is CPU work, not a browser solve, so it uses defaultTimeout rather than the longer recaptchaTimeout. A proxy applies only to the `challenge_url` fetch; an inline challenge never touches the network.
Testing against two live deployments -- bravenet.com (legacy SHA-256) and
wollastonpreschool.org.uk (PBKDF2/SHA-256, cost 50000) -- showed `number` was
silently missing for the second.
The two ALTCHA generations shape their tokens differently. A legacy payload is
the challenge document with a top-level `number` added. A proof-of-work v2
payload is `{"challenge": {...}, "solution": {"counter": N, ...}}` and has no
`number` at all, so decoding the token and reading `number` -- which is what
this did -- found nothing for every PBKDF2 site. That is the scheme altcha.org
documents today and recommends as the default, so it is the common case, not an
edge case.
The counter is now taken from the server's own `solution` object, which reports
both generations identically as `solution.number`, and is carried through the
poll for that purpose. Only when a poll did not include one -- a plain-text
poll -- is it dug out of the token, which now understands both nestings. A
server counter is trusted over the token: the server worked the answer out,
while the decode is only an inference from it. The `solution` object is
transient plumbing and is removed before the result reaches the caller.
Verified by recomputing both proofs-of-work independently against ALTCHA's own
algorithm: SHA-256(salt + counter) for the legacy scheme, and
PBKDF2(nonce || uint32be(counter), salt, cost, keyLength) for v2, whose derived
key must begin with the challenge's keyPrefix. Both reproduce exactly, and the
challenge signature survives in the token unmodified.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds ALTCHA to the PHP SDK, following the same shape GeeTest v3 used.
ALTCHA is proof-of-work rather than recognition: the site issues a challenge and the client brute-forces a number that satisfies it. There is no image, audio or text to read, so a solve is deterministic and takes milliseconds.
API
AsyncCapSkipinherits it, as it does every other solve method.Decisions worth reviewing
altcha(), notaltchacaptcha(). 2captcha-php spells italtchacaptcha, but this SDK uses one house name across all five CapSkip SDKs (geetest,turnstile,recaptcha), and consistency won.challenge_jsonaccepts an array, serialized for you — a form body would otherwise carry the string"Array"and drawERROR_BAD_PARAMETERS.base64_decode($code, true)runs in strict mode, so an answer that is not a token leaves the result untouched rather than decoding to garbage.defaultTimeout, notrecaptchaTimeout. This is CPU work, not a browser solve.challenge_urlfetch; an inline challenge never touches the network.Testing
vendor/bin/phpunit), up from 73 — newtests/AltchaTest.phpplus integration tests driving real HTTP through the built-in-server router, which now serves a genuine base64 ALTCHA payload so the decode path is actually exercised.challenge_urlfetch paths, with a challenge whose answer was known in advance — the SDK recovered the exact counter each time.