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.
- altcha-2.3.0/CHANGELOG.md +69 -0
- altcha-2.3.0/MANIFEST.in +2 -0
- {altcha-2.2.0/altcha.egg-info → altcha-2.3.0}/PKG-INFO +10 -7
- {altcha-2.2.0 → altcha-2.3.0}/README.md +9 -6
- {altcha-2.2.0 → altcha-2.3.0}/altcha/v2.py +283 -64
- {altcha-2.2.0 → altcha-2.3.0/altcha.egg-info}/PKG-INFO +10 -7
- {altcha-2.2.0 → altcha-2.3.0}/altcha.egg-info/SOURCES.txt +1 -0
- {altcha-2.2.0 → altcha-2.3.0}/setup.py +1 -1
- {altcha-2.2.0 → altcha-2.3.0}/tests/test_altcha_v2.py +378 -2
- altcha-2.2.0/MANIFEST.in +0 -1
- {altcha-2.2.0 → altcha-2.3.0}/LICENSE +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha/__init__.py +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha/altcha.py +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha/py.typed +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha/v1.py +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha.egg-info/dependency_links.txt +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/altcha.egg-info/top_level.txt +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/setup.cfg +0 -0
- {altcha-2.2.0 → altcha-2.3.0}/tests/test_altcha.py +0 -0
|
@@ -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.
|
altcha-2.3.0/MANIFEST.in
ADDED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: altcha
|
|
3
|
-
Version: 2.
|
|
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
|
|