Skip to main content

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"] and data["device.edk"] (verify_server returns these nested instead).
  • 'true'/'false' become bool, all-digit values int (including e.g. a params.zip of 01234, which becomes 1234), and digits.digits values float.
  • fields and reasons become 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_key and secret are the ID and secret of a restricted or full API key of the account that owns the payload's (public) API key. They are sent as Authorization: Basic base64(api_key:secret); an Authorization header in headers is replaced. api_key without secret raises ValueError before any request is sent.
  • The request body is {"payload": ...}; secret is not sent in the body (Sentinel v2 rejects it).
  • Without credentials, Sentinel v2 answers 401 and reason is 'API_KEY_REQUIRED'. A payload signed by a key of another account gets reason='API_KEY_NOT_ALLOWED'.
  • verification_data is the signed verification data as a nested dict, with keys split on .: result.verification_data["challenge"]["algorithm"] (v1's challengeAlgorithm), result.verification_data["device"]["edk"]. fields and reasons are lists; id, fieldsHash, device.edk and params.* 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/signature takes no credentials: omit api_key. secret (the payload's API key secret) is optional and sent in the body as {"payload": ..., "secret": ...}; Sentinel answers reason='WRONG_API_KEY_SECRET' when it is not the payload key's secret.
  • This also applies to the /v1/verify/signature alias 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)

Source distribution for altcha 2.4.0
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)

Table of built distributions (wheels) for altcha 2.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page