Solve the fork's ALTCHA captcha on login (and every request) #189

Manually merged
charles merged 0 commits from fix-altcha-captcha into main 2026-11-12 05:11:45 +00:00
Owner

Login against an instance with captcha turned on failed with "This instance requires a captcha…". The client now does the ALTCHA proof of work the server asks for and sends the request again, the same way the web app does.

What the fork does (the code in ~/src/fluxer-soundboard)

  • The server (fluxer_api/pkgs/captcha/src/providers/AltchaProvider.ts:10,67-78, altcha-lib 2.5.0 pow.js) uses ALTCHA v2 with PBKDF2/SHA-256, not the classic SHA-256 counter search. The key is PBKDF2-HMAC-SHA-256 with cost iterations and keyLength (32) bytes, the password is the nonce bytes followed by the counter as a big-endian u32, and the salt is the salt bytes. The server picks the counter at random in [max_counter/2, max_counter] and publishes the first 16 bytes of that key as keyPrefix. The client tries counters from 0 up until the key starts with keyPrefix.
  • Token (fluxer_app/src/features/auth/altcha/AltchaSolver.ts:38-40): base64(JSON.stringify({challenge:{parameters,signature},solution:{counter,derivedKey,time}})), sent in X-Captcha-Token (packages/constants/src/Headers.ts:27). verify (AltchaProvider.ts:80-105) checks the token length (at most 4096), the cost (>= minCost), the expiry (10 min), the HMAC signature and the HMAC key signature, and accepts each token only once.
  • CaptchaMiddleware.ts:77-95: when there is no token the server answers 400 CAPTCHA_REQUIRED. When the token is bad it answers 400 INVALID_CAPTCHA. Both answers carry a fresh challenge, and the cost can double up to 6 times.
  • CaptchaInterceptor.ts:76,80-143: the web app handles every request this way, with at most 2 solves per request, and gives up after 60 s (AltchaSolver.ts:10). It uses up to 8 workers that try interleaved counters.

Changes

  • fluxer-api: a new captcha module with challenge parsing, a pure solver (solve, threads × interleaved counters) and token encoding. ApiClient::execute solves the challenge and retries every request, with at most MAX_SOLVES = 2 solves. The search runs in spawn_blocking on at most 8 threads. It stops after 60 s, at the challenge's expiry by the local clock (an expiry that is already in the past counts as clock skew and is ignored), or when the request future is dropped. INVALID_CAPTCHA now maps to CaptchaRequired instead of a plain 400, which the core used to read as wrong credentials.
  • ApiError::CaptchaRequired now only means a captcha the client could not solve: unknown provider, malformed or non-PBKDF2 challenge, timeout, or both solutions refused.
  • fluxer-core (doc comments only) and fluxer-ui: the message now says what actually happened. While the client solves, the login screen keeps showing its usual "Logging in…", so there is no new UI.
  • New direct dependency: ring 0.17 in fluxer-api. It is already in the graph through rustls/reqwest, so nothing new gets compiled. The only Cargo.lock change is that one edge.

Tests

  • fixtures/captcha/altcha_login.json comes from the fork's own AltchaProvider: a throwaway node script outside both repos imported the provider directly. It holds a challenge, the solution and the web client's token, and the provider verified that token. The unit tests solve this vector on 1, 3 and 8 threads, and check that the encoded token matches the web client's byte for byte.
  • tests/captcha.rs has a wiremock server that issues and verifies tokens the way the fork does. The checker is itself checked against the fork's fixture token. The tests cover: CAPTCHA_REQUIRED then an accepted token; a rejected token, then the fresh challenge, then success (3 sends); retries exhausted (exactly 3 sends, then CaptchaRequired); login_totp and a GET also covered; unknown provider and INVALID_CAPTCHA without a challenge are not retried. Malformed bodies return errors and never panic.
  • I also cross-checked by hand: a token the Rust code made for the fixture challenge is accepted by the fork's AltchaProvider.verify.
  • Solve time in release mode on a Ryzen 9 9950X (with SHA extensions), at the default cost 5000 / max_counter 1000: about 260/390/520 ms on 1 thread and 35/53/70 ms on 8 threads, for counters 500/750/1000. To reproduce: cargo test --release -p fluxer-api --test captcha -- --ignored --nocapture.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally.

I did not change fluxer-devserver: it does not model a captcha, and it would need a signing server half to do so.

🤖 Generated with Claude Code

Login against an instance with captcha turned on failed with "This instance requires a captcha…". The client now does the ALTCHA proof of work the server asks for and sends the request again, the same way the web app does. ## What the fork does (the code in `~/src/fluxer-soundboard`) - The server (`fluxer_api/pkgs/captcha/src/providers/AltchaProvider.ts:10,67-78`, altcha-lib 2.5.0 `pow.js`) uses ALTCHA **v2 with `PBKDF2/SHA-256`**, not the classic SHA-256 counter search. The key is PBKDF2-HMAC-SHA-256 with `cost` iterations and `keyLength` (32) bytes, the password is the `nonce` bytes followed by the counter as a big-endian u32, and the salt is the `salt` bytes. The server picks the counter at random in `[max_counter/2, max_counter]` and publishes the first 16 bytes of that key as `keyPrefix`. The client tries counters from 0 up until the key starts with `keyPrefix`. - Token (`fluxer_app/src/features/auth/altcha/AltchaSolver.ts:38-40`): `base64(JSON.stringify({challenge:{parameters,signature},solution:{counter,derivedKey,time}}))`, sent in `X-Captcha-Token` (`packages/constants/src/Headers.ts:27`). `verify` (`AltchaProvider.ts:80-105`) checks the token length (at most 4096), the cost (`>= minCost`), the expiry (10 min), the HMAC signature and the HMAC key signature, and accepts each token only once. - `CaptchaMiddleware.ts:77-95`: when there is no token the server answers 400 `CAPTCHA_REQUIRED`. When the token is bad it answers 400 `INVALID_CAPTCHA`. Both answers carry a fresh challenge, and the cost can double up to 6 times. - `CaptchaInterceptor.ts:76,80-143`: the web app handles every request this way, with at most 2 solves per request, and gives up after 60 s (`AltchaSolver.ts:10`). It uses up to 8 workers that try interleaved counters. ## Changes - `fluxer-api`: a new `captcha` module with challenge parsing, a pure solver (`solve`, threads × interleaved counters) and token encoding. `ApiClient::execute` solves the challenge and retries every request, with at most `MAX_SOLVES = 2` solves. The search runs in `spawn_blocking` on at most 8 threads. It stops after 60 s, at the challenge's expiry by the local clock (an expiry that is already in the past counts as clock skew and is ignored), or when the request future is dropped. `INVALID_CAPTCHA` now maps to `CaptchaRequired` instead of a plain 400, which the core used to read as wrong credentials. - `ApiError::CaptchaRequired` now only means a captcha the client could not solve: unknown provider, malformed or non-PBKDF2 challenge, timeout, or both solutions refused. - `fluxer-core` (doc comments only) and `fluxer-ui`: the message now says what actually happened. While the client solves, the login screen keeps showing its usual "Logging in…", so there is no new UI. - New direct dependency: `ring` 0.17 in `fluxer-api`. It is already in the graph through rustls/reqwest, so nothing new gets compiled. The only `Cargo.lock` change is that one edge. ## Tests - `fixtures/captcha/altcha_login.json` comes from the **fork's own `AltchaProvider`**: a throwaway node script outside both repos imported the provider directly. It holds a challenge, the solution and the web client's token, and the provider verified that token. The unit tests solve this vector on 1, 3 and 8 threads, and check that the encoded token matches the web client's byte for byte. - `tests/captcha.rs` has a wiremock server that issues and verifies tokens the way the fork does. The checker is itself checked against the fork's fixture token. The tests cover: CAPTCHA_REQUIRED then an accepted token; a rejected token, then the fresh challenge, then success (3 sends); retries exhausted (exactly 3 sends, then `CaptchaRequired`); login_totp and a GET also covered; unknown provider and `INVALID_CAPTCHA` without a challenge are not retried. Malformed bodies return errors and never panic. - I also cross-checked by hand: a token the Rust code made for the fixture challenge is accepted by the fork's `AltchaProvider.verify`. - Solve time in release mode on a Ryzen 9 9950X (with SHA extensions), at the default cost 5000 / max_counter 1000: about 260/390/520 ms on 1 thread and 35/53/70 ms on 8 threads, for counters 500/750/1000. To reproduce: `cargo test --release -p fluxer-api --test captcha -- --ignored --nocapture`. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally. I did not change `fluxer-devserver`: it does not model a captcha, and it would need a signing server half to do so. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Solve the fork's ALTCHA captcha in fluxer-api
All checks were successful
ci / Linux (x86_64) (push) Successful in 16m3s
ci / Windows (x64) (push) Successful in 16m12s
d281e073da
A 400 CAPTCHA_REQUIRED / INVALID_CAPTCHA carrying an ALTCHA v2 challenge
is now solved by the client (PBKDF2-HMAC-SHA-256 over nonce || counter_be32,
counters from 0 until the key starts with keyPrefix) and the same request is
sent again with X-Captcha-Token, at most twice per request, as the web
app's CaptchaInterceptor does for every request. The search runs in
spawn_blocking on up to 8 threads, bounded by 60 s and the challenge's
expiry, and stops when the request is dropped. The token is byte for byte
the web client's encoding.

ApiError::CaptchaRequired is left for captchas the client cannot solve
(unknown provider, malformed challenge, timeout, both solutions refused);
INVALID_CAPTCHA maps to it instead of a plain 400 that the core read as
wrong credentials. The login screen's message says so.

Test vector fixtures/captcha/altcha_login.json was produced by the fork's
own AltchaProvider; the API tests run against a mock that verifies tokens
the way the fork does. Adds ring (already in the graph via rustls) as a
direct dependency of fluxer-api.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
charles manually merged commit 421838b9e4 into main 2026-11-12 05:11:45 +00:00
Sign in to join this conversation.
No description provided.