Skip to content

Add ALTCHA support (v1.2.0) - #2

Merged
capskip merged 2 commits into
mainfrom
add-altcha
Sep 12, 2026
Merged

capskip merged 2 commits into
mainfrom
add-altcha

Conversation

@capskip

@capskip capskip commented Sep 12, 2026

Copy link
Copy Markdown
Owner

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

// CapSkip fetches the challenge for you
$result = $solver->altcha('https://example.com/signup', [
    'challenge_url' => 'https://example.com/captcha/api/altcha/challenge',
]);

// ...or hand it the document you already have. No network request at all.
$result = $solver->altcha($url, ['challenge_json' => ['algorithm' => 'SHA-256', ...]]);

$result['token'];    // the base64 payload for the site's `altcha` form field
$result['number'];   // the counter that solved it
$result['code'];     // the same string as token

AsyncCapSkip inherits it, as it does every other solve method.

Decisions worth reviewing

  • Method named altcha(), not altchacaptcha(). 2captcha-php spells it altchacaptcha, but this SDK uses one house name across all five CapSkip SDKs (geetest, turnstile, recaptcha), and consistency won.
  • challenge_json accepts an array, serialized for you — a form body would otherwise carry the string "Array" and draw ERROR_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.
  • Both challenge params may be sent; the inline document wins. That matches CapSkip, which is deliberately more permissive here than 2Captcha's mutually-exclusive spelling.
  • Uses defaultTimeout, not recaptchaTimeout. This is CPU work, not a browser solve.
  • A proxy applies only to the challenge_url fetch; an inline challenge never touches the network.

Testing

  • 94 tests, 159 assertions pass (vendor/bin/phpunit), up from 73 — new tests/AltchaTest.php plus 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.
  • Verified end-to-end against a running CapSkip on :8080, on both the inline and the challenge_url fetch paths, with a challenge whose answer was known in advance — the SDK recovered the exact counter each time.

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.
@capskip
capskip merged commit 06a2ebf into main Sep 12, 2026
13 checks passed
@capskip
capskip deleted the add-altcha branch September 12, 2026 15:02
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.

1 participant