altcha 2.2.0__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,69 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6
+
7
+ ## [2.3.0] - 2026-10-04
8
+
9
+ Aligns the v2 API (`altcha.v2`) with the reference JavaScript implementation
10
+ ([altcha-lib](https://github.com/altcha-org/altcha-lib)) and hardens verification
11
+ against malformed payloads.
12
+
13
+ ### Upgrade notes
14
+
15
+ - Challenges signed by earlier versions may fail verification after upgrading if
16
+ their `data` contains `None`, floats, integer-like keys, or integers above 2^53, or
17
+ if they use a non-standard algorithm string (e.g. `'sha-512'`, `'SHA-1'`). Other
18
+ challenges keep the same signature and derived key. Challenges are short-lived, so
19
+ this only affects challenges issued just before the upgrade.
20
+ - `verify_solution` and `verify_server_signature` raise `ValueError` if `hmac_secret`
21
+ is empty.
22
+
23
+ ### Added
24
+
25
+ - `counter_mode` option (`'uint32'` default, or `'string'`) for `create_challenge`,
26
+ `solve_challenge` and `verify_solution`, matching altcha-lib's `counterMode`.
27
+ `'string'` encodes the counter as decimal digits, as in v1-compatible challenges.
28
+
29
+ ### Changed
30
+
31
+ - Challenge signatures use canonical JSON that is byte-identical to altcha-lib's
32
+ `canonicalJSON`. `null` values are kept. Numbers are formatted as in JavaScript
33
+ (`1e-7`, `1` for `1.0`, integers above 2^53 rounded to a double, `NaN` and
34
+ `Infinity` as `null`). Integer-like keys come first in numeric order, and other
35
+ keys are sorted by UTF-16 code units. Dicts inside arrays keep their key order, and
36
+ lone surrogates are escaped.
37
+ - Built-in SHA and PBKDF2 key derivation selects SHA-384 or SHA-512 only for the exact
38
+ algorithm strings `SHA-384`, `SHA-512`, `PBKDF2/SHA-384` and `PBKDF2/SHA-512`. Any
39
+ other string falls back to SHA-256, as in altcha-lib.
40
+ - `create_challenge` stores `key_prefix` in lowercase.
41
+ - `create_challenge` treats an empty `hmac_secret` as unset (unsigned challenge) and an
42
+ empty `hmac_key_secret` as unset (no `keySignature`).
43
+ - `create_challenge` raises `ValueError` when signing `data` that contains a
44
+ `__proto__` key outside arrays. altcha-lib leaves such keys out of the signature, so
45
+ they are rejected instead. Payloads containing them fail verification with
46
+ `invalid_signature`.
47
+ - `verify_server_signature` accepts only `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512` as
48
+ the payload `algorithm`. These are the digests available to altcha-lib.
49
+
50
+ ### Fixed
51
+
52
+ - `verify_solution` returns a result instead of raising on malformed client input:
53
+ - non-hex, odd-length or non-string `derivedKey`;
54
+ - non-integer or out-of-range `counter`;
55
+ - non-string or non-ASCII `signature` or `derivedKey`;
56
+ - non-numeric `expiresAt`;
57
+ - deeply nested `data`.
58
+ - With `hmac_key_secret`, a `derivedKey` containing whitespace no longer verifies.
59
+ - `verify_server_signature` returns `invalid_signature` instead of raising on a
60
+ malformed `algorithm` or `verificationData`. Lone surrogates in `verificationData`
61
+ are hashed as JavaScript's `TextEncoder` encodes them.
62
+ - `solve_challenge` now enforces `timeout` when `counter_start` and `counter_step`
63
+ never reach a multiple of 10 (e.g. `1` and `2`). Previously it could run forever.
64
+ - Uppercase key prefixes from other issuers: `verify_solution` no longer rejects valid
65
+ solutions for even-length prefixes, and `solve_challenge` now solves odd-length ones.
66
+ - Challenges issued by altcha-lib with explicit `null` parameters (`data`, `expiresAt`,
67
+ `memoryCost`, `parallelism`) now verify.
68
+ - Challenges whose `data` contains `null` or floats now verify between this library
69
+ and altcha-lib in both directions.
@@ -0,0 +1,2 @@
1
+ include README.md
2
+ include CHANGELOG.md
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: altcha
3
- Version: 2.2.0
3
+ Version: 2.3.0
4
4
  Summary: A library for creating and verifying challenges for ALTCHA.
5
5
  Home-page: https://github.com/altcha-org/altcha-lib-py
6
6
  Author: Daniel Regeci
@@ -170,7 +170,7 @@ The original ALTCHA proof of work. The client brute-forces a number `n` such tha
170
170
 
171
171
  ### V2
172
172
 
173
- #### `create_challenge(algorithm, cost, *, derive_key, counter, key_length, key_prefix, key_prefix_length, memory_cost, parallelism, expires_at, data, hmac_secret, hmac_key_secret, hmac_algorithm) → Challenge`
173
+ #### `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`
174
174
 
175
175
  Create a new v2 proof-of-work challenge.
176
176
 
@@ -180,6 +180,7 @@ Create a new v2 proof-of-work challenge.
180
180
  | `cost` | `int` | — | Algorithm-specific cost (iterations / passes). |
181
181
  | `derive_key` | callable | auto | `(parameters, salt: bytes, password: bytes) -> bytes`. Defaults to built-in for the algorithm. |
182
182
  | `counter` | `int` | `None` | Pre-solve with this counter (deterministic mode). |
183
+ | `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. |
183
184
  | `key_length` | `int` | `32` | Derived key length in bytes. |
184
185
  | `key_prefix` | `str` | `'00'` | Hex prefix the derived key must start with. |
185
186
  | `key_prefix_length` | `int` | `key_length // 2` | Bytes of the derived key used as prefix in deterministic mode. |
@@ -187,15 +188,15 @@ Create a new v2 proof-of-work challenge.
187
188
  | `parallelism` | `int` | `None` | Parallelism factor (Argon2id / scrypt). |
188
189
  | `expires_at` | `int` \| `datetime` | `None` | Expiry as a Unix timestamp or `datetime`. |
189
190
  | `data` | `dict` | `None` | Arbitrary metadata embedded in the challenge. |
190
- | `hmac_secret` | `str` | `None` | Secret for signing the challenge. If omitted, challenge is unsigned. |
191
- | `hmac_key_secret` | `str` | `None` | Secret for signing the derived key (fast verification path). |
191
+ | `hmac_secret` | `str` | `None` | Secret for signing the challenge. If omitted or empty, challenge is unsigned. |
192
+ | `hmac_key_secret` | `str` | `None` | Secret for signing the derived key (fast verification path). Ignored if empty. |
192
193
  | `hmac_algorithm` | `str` | `'SHA-256'` | HMAC digest algorithm. |
193
194
 
194
195
  Returns `Challenge`.
195
196
 
196
197
  ---
197
198
 
198
- #### `solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout) → Solution | None`
199
+ #### `solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout, counter_mode) → Solution | None`
199
200
 
200
201
  Solve a v2 challenge by brute-forcing counter values.
201
202
 
@@ -206,22 +207,24 @@ Solve a v2 challenge by brute-forcing counter values.
206
207
  | `counter_start` | `int` | `0` | First counter value to try. |
207
208
  | `counter_step` | `int` | `1` | Increment between attempts (use > 1 for partitioned parallel solving). |
208
209
  | `timeout` | `float` | `90.0` | Maximum seconds to spend. Returns `None` on timeout. |
210
+ | `counter_mode` | `str` | `'uint32'` | Counter encoding; must match the issuer's. |
209
211
 
210
212
  Returns `Solution` or `None`.
211
213
 
212
214
  ---
213
215
 
214
- #### `verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm) → VerifySolutionResult`
216
+ #### `verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm, counter_mode) → VerifySolutionResult`
215
217
 
216
218
  Verify a v2 challenge solution.
217
219
 
218
220
  | Parameter | Type | Default | Description |
219
221
  |---|---|---|---|
220
222
  | `payload` | `str` \| `Payload` | — | Base64-encoded JSON string or `Payload` object. |
221
- | `hmac_secret` | `str` | — | Secret used to verify the challenge signature. |
223
+ | `hmac_secret` | `str` | — | Secret used to verify the challenge signature. Raises `ValueError` if empty. |
222
224
  | `derive_key` | callable | auto | KDF function for re-derivation. |
223
225
  | `hmac_key_secret` | `str` | `None` | Secret for the fast verification path. |
224
226
  | `hmac_algorithm` | `str` | `'SHA-256'` | HMAC digest algorithm. |
227
+ | `counter_mode` | `str` | `'uint32'` | Counter encoding used when re-deriving the key; must match the issuer's. |
225
228
 
226
229
  Returns `VerifySolutionResult` with fields:
227
230
 
@@ -147,7 +147,7 @@ The original ALTCHA proof of work. The client brute-forces a number `n` such tha
147
147
 
148
148
  ### V2
149
149
 
150
- #### `create_challenge(algorithm, cost, *, derive_key, counter, key_length, key_prefix, key_prefix_length, memory_cost, parallelism, expires_at, data, hmac_secret, hmac_key_secret, hmac_algorithm) → Challenge`
150
+ #### `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`
151
151
 
152
152
  Create a new v2 proof-of-work challenge.
153
153
 
@@ -157,6 +157,7 @@ Create a new v2 proof-of-work challenge.
157
157
  | `cost` | `int` | — | Algorithm-specific cost (iterations / passes). |
158
158
  | `derive_key` | callable | auto | `(parameters, salt: bytes, password: bytes) -> bytes`. Defaults to built-in for the algorithm. |
159
159
  | `counter` | `int` | `None` | Pre-solve with this counter (deterministic mode). |
160
+ | `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. |
160
161
  | `key_length` | `int` | `32` | Derived key length in bytes. |
161
162
  | `key_prefix` | `str` | `'00'` | Hex prefix the derived key must start with. |
162
163
  | `key_prefix_length` | `int` | `key_length // 2` | Bytes of the derived key used as prefix in deterministic mode. |
@@ -164,15 +165,15 @@ Create a new v2 proof-of-work challenge.
164
165
  | `parallelism` | `int` | `None` | Parallelism factor (Argon2id / scrypt). |
165
166
  | `expires_at` | `int` \| `datetime` | `None` | Expiry as a Unix timestamp or `datetime`. |
166
167
  | `data` | `dict` | `None` | Arbitrary metadata embedded in the challenge. |
167
- | `hmac_secret` | `str` | `None` | Secret for signing the challenge. If omitted, challenge is unsigned. |
168
- | `hmac_key_secret` | `str` | `None` | Secret for signing the derived key (fast verification path). |
168
+ | `hmac_secret` | `str` | `None` | Secret for signing the challenge. If omitted or empty, challenge is unsigned. |
169
+ | `hmac_key_secret` | `str` | `None` | Secret for signing the derived key (fast verification path). Ignored if empty. |
169
170
  | `hmac_algorithm` | `str` | `'SHA-256'` | HMAC digest algorithm. |
170
171
 
171
172
  Returns `Challenge`.
172
173
 
173
174
  ---
174
175
 
175
- #### `solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout) → Solution | None`
176
+ #### `solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout, counter_mode) → Solution | None`
176
177
 
177
178
  Solve a v2 challenge by brute-forcing counter values.
178
179
 
@@ -183,22 +184,24 @@ Solve a v2 challenge by brute-forcing counter values.
183
184
  | `counter_start` | `int` | `0` | First counter value to try. |
184
185
  | `counter_step` | `int` | `1` | Increment between attempts (use > 1 for partitioned parallel solving). |
185
186
  | `timeout` | `float` | `90.0` | Maximum seconds to spend. Returns `None` on timeout. |
187
+ | `counter_mode` | `str` | `'uint32'` | Counter encoding; must match the issuer's. |
186
188
 
187
189
  Returns `Solution` or `None`.
188
190
 
189
191
  ---
190
192
 
191
- #### `verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm) → VerifySolutionResult`
193
+ #### `verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm, counter_mode) → VerifySolutionResult`
192
194
 
193
195
  Verify a v2 challenge solution.
194
196
 
195
197
  | Parameter | Type | Default | Description |
196
198
  |---|---|---|---|
197
199
  | `payload` | `str` \| `Payload` | — | Base64-encoded JSON string or `Payload` object. |
198
- | `hmac_secret` | `str` | — | Secret used to verify the challenge signature. |
200
+ | `hmac_secret` | `str` | — | Secret used to verify the challenge signature. Raises `ValueError` if empty. |
199
201
  | `derive_key` | callable | auto | KDF function for re-derivation. |
200
202
  | `hmac_key_secret` | `str` | `None` | Secret for the fast verification path. |
201
203
  | `hmac_algorithm` | `str` | `'SHA-256'` | HMAC digest algorithm. |
204
+ | `counter_mode` | `str` | `'uint32'` | Counter encoding used when re-deriving the key; must match the issuer's. |
202
205
 
203
206
  Returns `VerifySolutionResult` with fields:
204
207