altcha

Altcha is the official Python implementation for issuing and verifying ALTCHA proof-of-work challenges, the privacy-friendly, self-hostable alternative to traditional CAPTCHAs. Instead of asking a human to click images or solve puzzles, ALTCHA makes the client’s browser perform a small, tunable amount of computational work before a form can be submitted, filtering out most automated bots without third-party tracking or user friction.

The library ships two challenge generations side by side: the original SHA-based proof of work (v1) and a newer key-derivation-function-based scheme (v2) that supports memory-hard algorithms like Argon2id and scrypt for stronger resistance to GPU and ASIC solvers. It has zero runtime dependencies beyond the Python standard library (Argon2id support is opt-in via argon2-cffi), covers HMAC-based challenge signing and constant-time verification, and includes a client for ALTCHA’s remote Sentinel API so servers can offload verification instead of managing HMAC secrets themselves.

What You Get

• Challenge creation and verification - create_challenge() and verify_solution() generate and validate proof-of-work challenges for the v2 protocol, with an equivalent _v1 API for the legacy SHA-based scheme.
• Pluggable key derivation functions - built-in derive_key_sha, derive_key_pbkdf2, derive_key_scrypt, and derive_key_argon2id implementations, or supply a fully custom derive_key callable for any KDF.
• Deterministic and fast-verification modes - pre-solve a challenge server-side with a fixed counter, and sign the derived key with hmac_key_secret so verification can skip re-deriving the key entirely.
• Server-signature and remote verification helpers - verify_server_signature() checks ALTCHA-signed payloads locally, while verify_server() posts a payload to the ALTCHA Sentinel API for remote verification when you’d rather not manage an HMAC secret at all.
• Full type coverage - a py.typed marker and typed dataclass-style models (Challenge, Solution, Payload, VerifySolutionResult, etc.) for editor autocomplete and static analysis with mypy.
• Zero required dependencies - built entirely on the Python standard library (hashlib, hmac, secrets, urllib), with argon2-cffi needed only if you opt into Argon2id.

Common Use Cases

• Bot filtering on public forms - issue a challenge on a signup, contact, or comment form and reject submissions that don’t carry a valid solved payload.
• Login and password-reset throttling - require a solved v2 challenge with a tuned cost before processing authentication-sensitive requests, raising the cost for automated abuse without a visible puzzle for users.
• API endpoint protection without a CAPTCHA service - self-host the entire challenge/verify flow so no request data or user IP is sent to a third-party CAPTCHA provider.
• Delegated verification via Sentinel - use verify_server() in services that would rather not hold the HMAC secret locally, trusting ALTCHA’s hosted verification endpoint instead.

Under The Hood

Architecture The package splits cleanly into altcha/v1.py and altcha/v2.py, each self-contained with its own data classes (Challenge, Solution, Payload, result types) and a small set of module-level functions (create_challenge, solve_challenge, verify_solution) rather than classes with hidden state — every function takes its inputs explicitly and returns a plain result object. altcha/__init__.py re-exports the v2 API under its unprefixed names as the primary surface and the v1 API under _v1/V1-suffixed names, while altcha/altcha.py is a thin backward-compatibility shim re-exporting v1 under the historical import path. Key derivation is injected as a callable (derive_key) rather than hardcoded, so create_challenge, solve_challenge, and verify_solution all accept a custom KDF function and fall back to an internal _select_derive_key() dispatcher when none is given — this is the one dependency-injection seam in an otherwise straightforward functional design, and it’s what lets memory-hard algorithms and future custom algorithms slot in without touching the core challenge/verify logic.

Tech Stack The library targets Python 3.9+ and has zero required runtime dependencies, built entirely on the standard library: hashlib and hmac for hashing/signing, secrets for randomness, struct for the counter-to-bytes packing used in v2’s KDF password, and urllib for the stdlib-only HTTP transport behind verify_server(). Argon2id support is opt-in via the argon2-cffi package, guarded by a try/except import so the rest of the library works without it. Tooling is modern for a small library: pyproject-free setup.py packaging, ruff for linting and formatting and mypy for type checking via pre-commit, and a GitHub Actions test matrix spanning Python 3.9 through 3.14.

Code Quality Tests live in tests/test_altcha.py and tests/test_altcha_v2.py (roughly 1,000 lines combined) using the standard-library unittest framework, and they exercise both public functions and internal helpers directly — canonical JSON serialization, password packing, and each KDF implementation are tested in isolation alongside end-to-end challenge/solve/verify round trips. Security-sensitive comparisons (_constant_time_equal) consistently use hmac.compare_digest rather than ==, and the codebase carries a py.typed marker with type hints throughout, including from __future__ import annotations and precise Literal types for algorithm identifiers. Docstrings are extensive and Google-style, documenting parameters and return types for nearly every public function.

What Makes It Unique Most PoW-CAPTCHA libraries offer a single hashing scheme; this one supports both a legacy SHA-based protocol and a newer KDF-based protocol side by side without breaking existing integrations, and lets the KDF itself vary (PBKDF2, scrypt, Argon2id, or a fully custom function) so operators can tune the cost/memory-hardness tradeoff per endpoint. The “fast verification” path — signing the derived key itself so a server can verify a solution via one HMAC comparison instead of re-running the KDF — is a deliberate performance optimization not present in simpler PoW-CAPTCHA implementations, and the built-in verify_server() Sentinel client offers a documented way to verify challenges without ever holding the HMAC secret on the verifying service.