ALTCHA Python Library
The ALTCHA Python Library is a lightweight, zero-dependency library designed for creating and verifying ALTCHA challenges, specifically tailored for Python applications.
Compatibility
- Python 3.9+
Example
Installation
pip install altcha
For Argon2id support (optional):
pip install altcha argon2-cffi
Tests
python -m unittest discover tests
PoW v2
PoW v2 replaces the simple hash-matching approach of v1 with a key derivation function (KDF) proof of work. Instead of finding a number whose hash equals a target, the client must find a counter value whose derived key starts with a required prefix. This enables memory-hard algorithms (Argon2id, scrypt) that are more resistant to GPU/ASIC attacks.
Algorithms
| Algorithm string | KDF | Notes |
|---|---|---|
'SHA-256', 'SHA-384', 'SHA-512' |
Iterated SHA | Fast, for testing / low-security use |
'PBKDF2/SHA-256', 'PBKDF2/SHA-384', 'PBKDF2/SHA-512' |
PBKDF2 | Good default |
'SCRYPT' |
scrypt | Memory-hard |
'ARGON2ID' |
Argon2id | Memory-hard, requires argon2-cffi |
Quick start
from altcha import (
create_challenge,
solve_challenge,
verify_solution,
Payload,
)
HMAC_SECRET = "secret hmac key"
# Server: create a challenge
challenge = create_challenge(
algorithm="PBKDF2/SHA-256",
cost=5_000,
hmac_secret=HMAC_SECRET,
)
# Client: solve the challenge
solution = solve_challenge(challenge)
if solution is None:
raise RuntimeError("Challenge could not be solved in time")
# Client: encode and transmit the payload
payload_b64 = Payload(challenge, solution).to_base64()
# Server: verify
result = verify_solution(payload_b64, HMAC_SECRET)
print(result.verified) # True
Deterministic mode
Pass a counter to create_challenge to pre-solve the challenge. The derived key prefix is embedded in the challenge so the client must find exactly that counter. Combine with hmac_key_secret to enable fast server-side verification without re-deriving the key.
import secrets
counter = secrets.randbelow(5_000) + 5_000
challenge = create_challenge(
algorithm="PBKDF2/SHA-256",
cost=5_000,
counter=counter,
hmac_secret=HMAC_SECRET,
hmac_key_secret="key-signing-secret",
)
solution = solve_challenge(challenge)
if solution is None:
raise RuntimeError("Challenge could not be solved in time")
payload_b64 = Payload(challenge, solution).to_base64()
result = verify_solution(
payload_b64,
HMAC_SECRET,
hmac_key_secret="key-signing-secret", # enables fast path
)
print(result.verified) # True
Expiry
import datetime
challenge = create_challenge(
algorithm="PBKDF2/SHA-256",
cost=5_000,
expires_at=datetime.datetime.now(datetime.timezone.utc)
+ datetime.timedelta(minutes=10),
hmac_secret=HMAC_SECRET,
)
Custom derive_key
Pass your own derive_key function to use a custom or third-party KDF:
def my_derive_key(parameters, salt: bytes, password: bytes) -> bytes: ...
challenge = create_challenge(
algorithm="MY-ALGO",
cost=1,
derive_key=my_derive_key,
hmac_secret=HMAC_SECRET,
)
PoW v1 (legacy)
The original ALTCHA proof of work. The client brute-forces a number n such that hash(salt + n) == challenge. Available under the _v1 / V1 suffix.
API reference
V2
create_challenge(algorithm, cost, *, derive_key, counter, counter_mode, key_length, key_prefix, key_prefix_length, memory_cost, parallelism, expires_at, data, hmac_secret, hmac_key_secret, hmac_algorithm) → Challenge
Create a new v2 proof-of-work challenge.
| Parameter | Type | Default | Description |
|---|---|---|---|
algorithm |
str |
— | KDF algorithm identifier (e.g. 'PBKDF2/SHA-256', 'ARGON2ID', 'SCRYPT', 'SHA-256'). |
cost |
int |
— | Algorithm-specific cost (iterations / passes). |
derive_key |
callable | auto | (parameters, salt: bytes, password: bytes) -> bytes. Defaults to built-in for the algorithm. |
counter |
int |
None |
Pre-solve with this counter (deterministic mode). |
counter_mode |
str |
'uint32' |
Counter encoding in the KDF password: 'uint32' (big-endian) or 'string' (decimal digits, V1 compatibility). Solver and verifier must use the same mode. |
key_length |
int |
32 |
Derived key length in bytes. |
key_prefix |
str |
'00' |
Hex prefix the derived key must start with. |
key_prefix_length |
int |
key_length // 2 |
Bytes of the derived key used as prefix in deterministic mode. |
memory_cost |
int |
None |
Memory cost in KiB (Argon2id / scrypt). |
parallelism |
int |
None |
Parallelism factor (Argon2id / scrypt). |
expires_at |
int | datetime |
None |
Expiry as a Unix timestamp or datetime. |
data |
dict |
None |
Arbitrary metadata embedded in the challenge. |
hmac_secret |
str |
None |
Secret for signing the challenge. If omitted or empty, challenge is unsigned. |
hmac_key_secret |
str |
None |
Secret for signing the derived key (fast verification path). Ignored if empty. |
hmac_algorithm |
str |
'SHA-256' |
HMAC digest algorithm. |
Returns Challenge.
solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout, counter_mode) → Solution | None
Solve a v2 challenge by brute-forcing counter values.
| Parameter | Type | Default | Description |
|---|---|---|---|
challenge |
Challenge |
— | The challenge to solve. |
derive_key |
callable | auto | KDF function. Defaults to built-in for the algorithm. |
counter_start |
int |
0 |
First counter value to try. |
counter_step |
int |
1 |
Increment between attempts (use > 1 for partitioned parallel solving). |
timeout |
float |
90.0 |
Maximum seconds to spend. Returns None on timeout. |
counter_mode |
str |
'uint32' |
Counter encoding; must match the issuer's. |
Returns Solution or None.
verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm, counter_mode) → VerifySolutionResult
Verify a v2 challenge solution.
| Parameter | Type | Default | Description |
|---|---|---|---|
payload |
str | Payload |
— | Base64-encoded JSON string or Payload object. |
hmac_secret |
str |
— | Secret used to verify the challenge signature. Raises ValueError if empty. |
derive_key |
callable | auto | KDF function for re-derivation. |
hmac_key_secret |
str |
None |
Secret for the fast verification path. |
hmac_algorithm |
str |
'SHA-256' |
HMAC digest algorithm. |
counter_mode |
str |
'uint32' |
Counter encoding used when re-deriving the key; must match the issuer's. |
Returns VerifySolutionResult with fields:
| Field | Type | Description |
|---|---|---|
verified |
bool |
True if the solution is valid. |
expired |
bool |
True if the challenge has expired. |
invalid_signature |
bool | None |
True if the challenge signature is missing or wrong. |
invalid_solution |
bool | None |
True if the solution is incorrect. |
time |
float |
Time taken for verification in milliseconds. |
error |
str | None |
Set if the payload could not be parsed. |
Built-in derive_key functions
| Function | Algorithm |
|---|---|
derive_key_sha(parameters, salt, password) |
Iterated SHA (SHA-256/384/512) |
derive_key_pbkdf2(parameters, salt, password) |
PBKDF2 (SHA-256/384/512) |
derive_key_scrypt(parameters, salt, password) |
scrypt |
derive_key_argon2id(parameters, salt, password) |
Argon2id (requires argon2-cffi) |
Server Signature Verification
verify_fields_hash(form_data, fields, fields_hash, algorithm) → bool
Verifies the hash of specific form fields: the hex hash (algorithm, e.g. 'SHA-256') of
the values of fields in form_data, joined with \n, must equal fields_hash.
verify_server_signature(payload, hmac_secret, *, hmac_algorithm) → VerifyServerSignatureResult
Verifies an ALTCHA server signature locally, e.g. the payload of Sentinel's
POST /v2/verify (or /v1/verify) response, with the secret of the API key that signed
it. Sentinel v1 and v2 sign the same way, so this works for both. To have Sentinel check
the payload instead, use verify_server (below).
from altcha import verify_fields_hash, verify_server_signature
result = verify_server_signature(payload, API_KEY_SECRET)
if result.verified:
data = result.verification_data
# Detect tampering with the submitted form fields
if data.get("fields") and not verify_fields_hash(
form_data, data["fields"], data["fieldsHash"], "SHA-256"
):
...
| Parameter | Type | Default | Description |
|---|---|---|---|
payload |
str | ServerSignaturePayload |
— | Base64-encoded JSON string or ServerSignaturePayload object. Its algorithm (hash of verificationData) must be 'SHA-1', 'SHA-256', 'SHA-384' or 'SHA-512'. |
hmac_secret |
str | bytes |
— | Secret used to verify the HMAC signature (the API key secret for Sentinel). Raises ValueError if empty. |
hmac_algorithm |
str |
'SHA-256' |
HMAC digest algorithm. |
Returns VerifyServerSignatureResult with fields:
| Field | Type | Description |
|---|---|---|
verified |
bool |
True if the signature is valid, the payload has not expired, and verified is true in both the payload and the signed verification data. |
expired |
bool |
True if the signed expire is in the past. |
invalid_signature |
bool |
True if the signature does not match, or the payload is malformed. |
invalid_solution |
bool |
True if verified is not true in the payload or in the signed verification data. |
time |
float |
Time taken for verification in milliseconds. |
verification_data |
dict | None |
The signed verification data, parsed with parse_verification_data; None unless verified. |
parse_verification_data(data) turns the URL-encoded verification data into a flat dict:
- Keys stay as signed, e.g.
data["challenge.algorithm"]anddata["device.edk"](verify_serverreturns these nested instead). 'true'/'false'becomebool, all-digit valuesint(including e.g. aparams.zipof01234, which becomes1234), anddigits.digitsvaluesfloat.fieldsandreasonsbecome lists.- Keys with empty values are left out.
Unlike Sentinel v2's /v2/verify/signature (via verify_server), local verification does
not prevent reuse: a valid payload verifies again until expire. Reject repeated ids
yourself if that matters.
verify_server(payload, url, secret, *, api_key, headers, timeout, retries, retry_delay, retry_backoff, http_post) → VerifyServerResult
Verifies a payload remotely via the ALTCHA Sentinel verify signature API, instead of
checking the HMAC signature locally. Avoids managing the HMAC secret on your server, at the
cost of a network round-trip. Both Sentinel v2 (POST /v2/verify/signature) and Sentinel v1
(POST /v1/verify/signature) are supported; they differ in how the request is authenticated.
Sentinel v2
from altcha import verify_server
result = verify_server(
payload, # the payload received from POST /v2/verify
url="https://sentinel.example.com/v2/verify/signature",
api_key=SENTINEL_API_KEY, # id of a restricted or full API key (key_...)
secret=SENTINEL_API_KEY_SECRET, # its secret (sec_...)
timeout=10,
retries=2,
)
if result.verified:
...
api_keyandsecretare the ID and secret of arestrictedorfullAPI key of the account that owns the payload's (public) API key. They are sent asAuthorization: Basic base64(api_key:secret); anAuthorizationheader inheadersis replaced.api_keywithoutsecretraisesValueErrorbefore any request is sent.- The request body is
{"payload": ...};secretis not sent in the body (Sentinel v2 rejects it). - Without credentials, Sentinel v2 answers
401andreasonis'API_KEY_REQUIRED'. A payload signed by a key of another account getsreason='API_KEY_NOT_ALLOWED'. verification_datais the signed verification data as a nested dict, with keys split on.:result.verification_data["challenge"]["algorithm"](v1'schallengeAlgorithm),result.verification_data["device"]["edk"].fieldsandreasonsare lists;id,fieldsHash,device.edkandparams.*stay strings.
Sentinel v1
from altcha import verify_server
result = verify_server(
payload, # the payload received from POST /v1/verify
url="https://sentinel.example.com/v1/verify/signature",
secret=API_KEY_SECRET, # optional, checked against the payload's API key
timeout=10,
retries=2,
)
if result.verified:
...
/v1/verify/signaturetakes no credentials: omitapi_key.secret(the payload's API key secret) is optional and sent in the body as{"payload": ..., "secret": ...}; Sentinel answersreason='WRONG_API_KEY_SECRET'when it is not the payload key's secret.- This also applies to the
/v1/verify/signaturealias Sentinel v2 serves with[server] v1_compat = true.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
payload |
str | ServerSignaturePayload | dict |
— | The payload to verify. |
url |
str |
— | Full URL of the Sentinel endpoint: /v2/verify/signature (v2) or /v1/verify/signature (v1). |
secret |
str |
None |
v2: secret of api_key, required with it. v1: API key secret sent in the body and checked against the payload's API key. |
api_key |
str |
None |
v2 only: ID of a restricted or full API key, sent with secret as HTTP Basic credentials. |
headers |
dict |
None |
Additional headers to send with the request. |
timeout |
float |
10 |
Per-attempt request timeout in seconds. |
retries |
int |
0 |
Number of retry attempts after the first try. |
retry_delay |
float |
0.3 |
Base delay in seconds between retries. |
retry_backoff |
str |
'exponential' |
'fixed' or 'exponential' backoff. |
http_post |
callable | stdlib urllib |
Transport override: (url, body, headers, timeout) -> (status, body). |
Errors and retries
Failures never raise; they return verified=False with a reason. 4xx responses (bad
payload, missing or wrong credentials, rate limit) are definitive and returned at once.
Network errors, other error statuses (e.g. 5xx) and invalid response bodies are retried up
to retries times. For an error response, reason is the code of Sentinel's error body
(v2: {"code", "error", "statusCode"}), else its error (v1), else 'HTTP_<status>'.
Returns VerifyServerResult with fields:
| Field | Type | Description |
|---|---|---|
verified |
bool |
True if Sentinel confirmed the payload is valid. |
reason |
str | None |
Why verification failed: Sentinel's reason (e.g. 'PAYLOAD_ALREADY_USED', 'INVALID_PAYLOAD', 'API_KEY_NOT_ALLOWED' (v2), 'WRONG_API_KEY_SECRET' (v1)), the error code of an HTTP error response, 'INVALID_RESPONSE', or a network error message. |
api_key |
str | None |
The API key associated with the payload, if returned. |
verification_data |
dict | None |
Verification data returned by Sentinel (nested dict), if returned. |
V1 (legacy)
create_challenge_v1(options) → ChallengeV1
Creates a new v1 challenge.
ChallengeOptionsV1 parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
algorithm |
str |
'SHA-256' |
Hashing algorithm ('SHA-1', 'SHA-256', 'SHA-512'). |
max_number |
int |
1,000,000 |
Upper bound for the random number. |
salt_length |
int |
12 |
Length of the random salt in bytes. |
hmac_key |
str |
— | Required HMAC key. |
salt |
str |
auto | Optional salt. Random if omitted. |
number |
int |
auto | Optional number. Random if omitted. |
expires |
datetime |
None |
Optional expiration time. |
params |
dict |
None |
Optional URL-encoded query parameters appended to the salt. |
verify_server_signature_v1(payload, hmac_key) → (bool, ServerSignatureVerificationData | None, str | None)
Verifies a server signature with the v1 API. Returns (verified, data, error), where data
exposes the known fields (classification, expire, fields, fieldsHash, score, …)
as attributes. Prefer verify_server_signature.
verify_solution_v1(payload, hmac_secret, check_expires) → (bool, str | None)
Verifies a v1 solution payload.
solve_challenge_v1(challenge, salt, algorithm, max_number, start) → SolutionV1 | None
Brute-forces a v1 challenge.
extract_params_v1(payload) → dict
Extracts URL parameters from the payload's salt.
License
MIT
Metadata
Release files for altcha 2.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| altcha-2.4.0.tar.gz | 42.6 kB | With provenance | Details for altcha-2.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| altcha-2.4.0-py3-none-any.whl | Python 3 | none | any | Details for altcha-2.4.0-py3-none-any.whl |
Total release size: 69.5 kB
Release files / altcha-2.4.0.tar.gz
| Download URL | altcha-2.4.0.tar.gz |
|---|---|
| Size | 42.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
56cea48b2e1b438d8a1601017fad294361dca89b4a6ef80e18f8ccb8bc917733
|
|
BLAKE2b-256 checksum How to use checksums |
89579c0d918044bfaac2c068fa373a06c27e45ccb09048c96d11ef1096758179
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / altcha-2.4.0-py3-none-any.whl
| Download URL | altcha-2.4.0-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6eff40a521cfa92dd4f64463152beea9966b9bfd03ae28d86ce10dfd08e33498
|
|
BLAKE2b-256 checksum How to use checksums |
29d154d8bb36687f1031e8c65e11783c3785e6cea9bb0a67752a3c084504619f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for altcha 2.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for altcha-2.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.