easypow 0.1.0__tar.gz

easypow-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+/dist/
+wheels/
+*.egg-info
+
+.*
+!.gitignore
+!*/.prettierrc.json
+*.lock
+
+# C build artifacts
+/c/solve
+/c/solve_sodium

easypow-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: easypow
+Version: 0.1.0
+Summary: Antibot Proof-of-Work protection to verify browsers on web apps.
+Project-URL: Repository, https://git.zi.fi/LeoVasanko/easypow
+Project-URL: Issues, https://github.com/LeoVasanko/easypow
+Author: Leo Vasanko
+License-Expression: MIT OR Unlicense
+Keywords: antibot,proof-of-work,web-security
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: base64url>=1.1.1
+Description-Content-Type: text/markdown
+
+# Easy PoW for Web Apps
+
+A defense for web services against bots and other spam. A proof-of-work CAPTCHA asks a browser to perform a small amount of computation before a request is accepted. This can be used to reduce automated abuse by making high-volume requests more costly to them. EasyPoW is intended for Python backends that issue proof-of-work challenges to browser clients and verify the returned solutions.
+
+```sh
+uv add easypow
+```
+
+The basic flow is that the server creates a challenge, that is sent to client, and the client responds with the solution, and after validation we allow their original request to proceed.
+
+## Python backend
+
+```python
+import easypow
+
+# Within your WebSocket handler:
+challenge = easypow.generate(5.0)      # ~seconds to solve
+await ws.send_text(challenge)
+# Client runs JS:                        solution = await solve(challenge)
+solution = await ws.receive_text()
+easypow.validate(challenge, solution)  # raises ValueError if invalid
+```
+
+The same can be adapted to any protocol you have, of course, while maintaining some way of keeping the challenge on server, making sure that clients cannot use the same one more than once. WebSockets are particularly useful because we can simply keep challenge in a local variable and do the dance only when the socket is first connected, and then continuing without any further verifications through the ordinary chat your application would do.
+
+Also useful is to start calculating in the background, and submit a response with the next command that requires PoW. This way the verification can happen without disturbing the user, if he spends at least that time filling up a form or whatever activity it is you wish to protect.
+
+## JavaScript solver
+
+Download [easypow.js](https://git.zi.fi/LeoVasanko/easypow/raw/branch/main/easypow/easypow.js) module to your project. If needed programmatically, this is also available from the Python module as `easypow.js` string or via CLI.
+
+It provides `solve` both as a named and as the default export:
+
+```js
+import solve from './easypow.js'
+
+const solution = await solve(challenge)  // optional AbortSignal as 2nd arg
+```
+
+### Plain function version
+
+If it better suits you, the entire solution function can be copied from here to where ever you need it.
+
+```js
+async function solve(challenge, signal) {
+  const B64URL = { alphabet: 'base64url', omitPadding: true }
+  const c = Uint8Array.fromBase64(challenge, B64URL)
+  const key = await crypto.subtle.importKey('raw', c, 'PBKDF2', false, ['deriveBits'])
+  const salt = new Uint32Array(1)
+  const args = { name: 'PBKDF2', salt, iterations: 1 << (c[1] & 0xF), hash: 'SHA-512' }
+  const mask = (1 << (c[1] >> 4)) - 1
+  const fragments = []
+  for (let w=c[0]; w-->0;) {
+    if (signal?.aborted) throw new DOMException('PoW operation aborted', 'AbortError')
+    do {
+      ++salt[0]
+    } while (new Uint32Array(await crypto.subtle.deriveBits(args, key, 32))[0] & mask)
+    fragments.push(new Uint8Array(salt.buffer).toBase64(B64URL).replace(/A+$/, ''))
+  }
+  return fragments.join('.')
+}
+```
+
+## CLI
+
+Run via `python -m easypow <command> <args>`. Supported commands are **generate**, **validate**, **solve** and **js**, corresponding to the Python API. No console scripts are installed because this module is mainly intended to be used via Python API by other software that might not want such pollution.
+
+## Design principles
+
+Many proof-of-work schemes use an exponential difficulty measure: for example, the number of initial zero bits required in a hash. Each additional bit roughly doubles the expected work, which gives rather coarse control over difficulty. The search is also inherently random and memoryless. If a challenge is expected to take 5 seconds and 10 seconds have already passed without a solution, the expected remaining time is still about 5 seconds. An unlucky solve can therefore take much longer than intended.
+
+To make the work both finer-grained and more predictable, we use smaller rounds and require several of them to be solved. A basic round takes about 0.1 seconds on the target machine, but with large random variation. Requiring 10 independent rounds still gives about 1 second of expected work, while averaging out much of that randomness: the total time is considerably more concentrated around 1 second than a single harder 1-second search. The solution contains the nonce found for each round, and the server verifies them individually.
+
+This also separates two useful controls. The zero-bit requirement determines the asymmetry between solving and verification, while the number of required rounds controls total work approximately linearly. Difficulty can therefore be adjusted in small time increments without weakening the basic solve/verify ratio.
+
+Verification itself must be cheap in two ways. First, invalid submissions must not be able to consume substantial server resources: an attacker can always send arbitrary solutions without doing any work. Second, producing a valid solution must be much more expensive than checking one.
+
+Checking a candidate still requires performing the underlying cryptographic operation, so that operation cannot be made arbitrarily expensive. Conversely, if it is made too cheap and the difficulty is moved entirely into requiring more zero bits, JavaScript overhead and other supporting machinery begin to dominate, making browser performance much worse than native code. The implementation therefore uses PBKDF2-SHA512 through Web Crypto with 128 iterations. That would be extremely low for password hashing, but here it places each trial in a useful range: expensive enough that native cryptographic execution dominates, while still cheap for the server to verify.
+
+With the minimal zero-bit requirement, producing a valid round costs 2048 times as much expected work as verifying one candidate. Because a complete solution consists of a sequence of valid rounds, the server can stop at the first failure. Random or fabricated submissions therefore normally cost only a single cheap verification, while a valid solution requires the client to have paid the full proof-of-work cost. Larger work factors increase this asymmetry further because we require a higher number of zero bits while keeping the round count restrained.
+
+Finally, we wish the function be abortable, while allowing the browser to keep running. AbortSignals produce a useful mechanism for external termination, but checking for the signal is expensive. The current implementation checks this between rounds only, and for that reason also we wish to keep the basic round fairly quick. This scales well from 0.1s to a few minutes expected cost in the current implementation. For the sake of simplicity, we did not implement further break points or infinite scaling.

easypow-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Easy PoW for Web Apps
+
+A defense for web services against bots and other spam. A proof-of-work CAPTCHA asks a browser to perform a small amount of computation before a request is accepted. This can be used to reduce automated abuse by making high-volume requests more costly to them. EasyPoW is intended for Python backends that issue proof-of-work challenges to browser clients and verify the returned solutions.
+
+```sh
+uv add easypow
+```
+
+The basic flow is that the server creates a challenge, that is sent to client, and the client responds with the solution, and after validation we allow their original request to proceed.
+
+## Python backend
+
+```python
+import easypow
+
+# Within your WebSocket handler:
+challenge = easypow.generate(5.0)      # ~seconds to solve
+await ws.send_text(challenge)
+# Client runs JS:                        solution = await solve(challenge)
+solution = await ws.receive_text()
+easypow.validate(challenge, solution)  # raises ValueError if invalid
+```
+
+The same can be adapted to any protocol you have, of course, while maintaining some way of keeping the challenge on server, making sure that clients cannot use the same one more than once. WebSockets are particularly useful because we can simply keep challenge in a local variable and do the dance only when the socket is first connected, and then continuing without any further verifications through the ordinary chat your application would do.
+
+Also useful is to start calculating in the background, and submit a response with the next command that requires PoW. This way the verification can happen without disturbing the user, if he spends at least that time filling up a form or whatever activity it is you wish to protect.
+
+## JavaScript solver
+
+Download [easypow.js](https://git.zi.fi/LeoVasanko/easypow/raw/branch/main/easypow/easypow.js) module to your project. If needed programmatically, this is also available from the Python module as `easypow.js` string or via CLI.
+
+It provides `solve` both as a named and as the default export:
+
+```js
+import solve from './easypow.js'
+
+const solution = await solve(challenge)  // optional AbortSignal as 2nd arg
+```
+
+### Plain function version
+
+If it better suits you, the entire solution function can be copied from here to where ever you need it.
+
+```js
+async function solve(challenge, signal) {
+  const B64URL = { alphabet: 'base64url', omitPadding: true }
+  const c = Uint8Array.fromBase64(challenge, B64URL)
+  const key = await crypto.subtle.importKey('raw', c, 'PBKDF2', false, ['deriveBits'])
+  const salt = new Uint32Array(1)
+  const args = { name: 'PBKDF2', salt, iterations: 1 << (c[1] & 0xF), hash: 'SHA-512' }
+  const mask = (1 << (c[1] >> 4)) - 1
+  const fragments = []
+  for (let w=c[0]; w-->0;) {
+    if (signal?.aborted) throw new DOMException('PoW operation aborted', 'AbortError')
+    do {
+      ++salt[0]
+    } while (new Uint32Array(await crypto.subtle.deriveBits(args, key, 32))[0] & mask)
+    fragments.push(new Uint8Array(salt.buffer).toBase64(B64URL).replace(/A+$/, ''))
+  }
+  return fragments.join('.')
+}
+```
+
+## CLI
+
+Run via `python -m easypow <command> <args>`. Supported commands are **generate**, **validate**, **solve** and **js**, corresponding to the Python API. No console scripts are installed because this module is mainly intended to be used via Python API by other software that might not want such pollution.
+
+## Design principles
+
+Many proof-of-work schemes use an exponential difficulty measure: for example, the number of initial zero bits required in a hash. Each additional bit roughly doubles the expected work, which gives rather coarse control over difficulty. The search is also inherently random and memoryless. If a challenge is expected to take 5 seconds and 10 seconds have already passed without a solution, the expected remaining time is still about 5 seconds. An unlucky solve can therefore take much longer than intended.
+
+To make the work both finer-grained and more predictable, we use smaller rounds and require several of them to be solved. A basic round takes about 0.1 seconds on the target machine, but with large random variation. Requiring 10 independent rounds still gives about 1 second of expected work, while averaging out much of that randomness: the total time is considerably more concentrated around 1 second than a single harder 1-second search. The solution contains the nonce found for each round, and the server verifies them individually.
+
+This also separates two useful controls. The zero-bit requirement determines the asymmetry between solving and verification, while the number of required rounds controls total work approximately linearly. Difficulty can therefore be adjusted in small time increments without weakening the basic solve/verify ratio.
+
+Verification itself must be cheap in two ways. First, invalid submissions must not be able to consume substantial server resources: an attacker can always send arbitrary solutions without doing any work. Second, producing a valid solution must be much more expensive than checking one.
+
+Checking a candidate still requires performing the underlying cryptographic operation, so that operation cannot be made arbitrarily expensive. Conversely, if it is made too cheap and the difficulty is moved entirely into requiring more zero bits, JavaScript overhead and other supporting machinery begin to dominate, making browser performance much worse than native code. The implementation therefore uses PBKDF2-SHA512 through Web Crypto with 128 iterations. That would be extremely low for password hashing, but here it places each trial in a useful range: expensive enough that native cryptographic execution dominates, while still cheap for the server to verify.
+
+With the minimal zero-bit requirement, producing a valid round costs 2048 times as much expected work as verifying one candidate. Because a complete solution consists of a sequence of valid rounds, the server can stop at the first failure. Random or fabricated submissions therefore normally cost only a single cheap verification, while a valid solution requires the client to have paid the full proof-of-work cost. Larger work factors increase this asymmetry further because we require a higher number of zero bits while keeping the round count restrained.
+
+Finally, we wish the function be abortable, while allowing the browser to keep running. AbortSignals produce a useful mechanism for external termination, but checking for the signal is expensive. The current implementation checks this between rounds only, and for that reason also we wish to keep the basic round fairly quick. This scales well from 0.1s to a few minutes expected cost in the current implementation. For the sake of simplicity, we did not implement further break points or infinite scaling.

easypow-0.1.0/c/solve.c

@@ -0,0 +1,76 @@
+/* Proof-of-Work solver using PBKDF2-HMAC-SHA512, port of solver.js.
+ *
+ * Usage: solve <challenge>
+ *   challenge: 12-char base64url string decoding to 9 bytes:
+ *     [0] work w, [1] difficulty (high nibble z = zero bits,
+ *     low nibble n = iteration exponent), [2..8] random.
+ * Prints the dot-separated base64url solution.
+ *
+ * Build: cc -O2 -o solve solve.c -lcrypto
+ */
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <openssl/evp.h>
+
+static const char B64[] =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+static size_t b64url_decode(const char *in, uint8_t *out) {
+    size_t len = strlen(in), n = 0;
+    uint32_t acc = 0;
+    int bits = 0;
+    for (size_t i = 0; i < len; i++) {
+        const char *p = strchr(B64, in[i]);
+        if (!p) { fprintf(stderr, "invalid base64url\n"); exit(1); }
+        acc = (acc << 6) | (uint32_t)(p - B64);
+        bits += 6;
+        if (bits >= 8) { bits -= 8; out[n++] = (uint8_t)(acc >> bits); }
+    }
+    return n;
+}
+
+static void b64url_encode(const uint8_t *in, size_t len, char *out) {
+    size_t n = 0;
+    uint32_t acc = 0;
+    int bits = 0;
+    for (size_t i = 0; i < len; i++) {
+        acc = (acc << 8) | in[i];
+        bits += 8;
+        while (bits >= 6) { bits -= 6; out[n++] = B64[(acc >> bits) & 0x3F]; }
+    }
+    if (bits) out[n++] = B64[(acc << (6 - bits)) & 0x3F];
+    out[n] = '\0';
+}
+
+int main(int argc, char **argv) {
+    if (argc != 2) { fprintf(stderr, "usage: solve <challenge>\n"); return 1; }
+
+    uint8_t c[9];
+    if (b64url_decode(argv[1], c) != 9) {
+        fprintf(stderr, "challenge must decode to 9 bytes\n");
+        return 1;
+    }
+    unsigned w = c[0], z = c[1] >> 4, iterations = 1u << (c[1] & 0xF);
+    uint32_t mask = (1u << z) - 1;
+
+    uint32_t nonce = 0;
+    int first = 1;
+    while (w--) {
+        uint8_t digest[4];
+        do {
+            nonce++;
+            PKCS5_PBKDF2_HMAC((const char *)c, 9, (uint8_t *)&nonce, 4,
+                              (int)iterations, EVP_sha512(), 4, digest);
+        } while (*(uint32_t *)digest & mask);
+        char frag[7];
+        b64url_encode((uint8_t *)&nonce, 4, frag);
+        size_t len = strlen(frag);
+        while (len && frag[len - 1] == 'A') frag[--len] = '\0';
+        printf("%s%s", first ? "" : ".", frag);
+        first = 0;
+    }
+    printf("\n");
+    return 0;
+}

easypow-0.1.0/dist/.gitignore

@@ -0,0 +1 @@
+*

easypow-0.1.0/easypow/__init__.py

@@ -0,0 +1,10 @@
+"""Proof-of-Work captcha using PBKDF2-SHA512, with a bundled JavaScript solver."""
+
+from importlib.resources import files
+
+from easypow.pow import generate, solve, validate
+
+__all__ = ["generate", "js", "solve", "validate"]
+
+js: str = files("easypow").joinpath("easypow.js").read_text(encoding="utf-8")
+"""Source of the bundled JavaScript PoW solver module."""

easypow-0.1.0/easypow/__main__.py

@@ -0,0 +1,89 @@
+"""Command-line interface: python -m easypow <command>."""
+
+import sys
+from pathlib import Path
+
+from easypow import generate, js, solve, validate
+
+USAGE = """\
+usage: python -m easypow <command> [args]
+
+Commands (unambiguous prefixes accepted):
+  generate [seconds]            Generate a challenge (default 1.0s of work)
+  solve <challenge>             Solve a challenge
+  validate <challenge> <sol.>   Validate a solution (exit 1 if invalid)
+  js [filename]                 Dump the JS solver module (stdout or file)
+"""
+
+_COMMANDS = ("generate", "solve", "validate", "js")
+
+
+def _match(command: str) -> str:
+    """Match a command by unambiguous prefix."""
+    if command in _COMMANDS:
+        return command
+    matches = [c for c in _COMMANDS if c.startswith(command)]
+    if len(matches) == 1:
+        return matches[0]
+    msg = f"Unknown or ambiguous command: {command!r}"
+    raise ValueError(msg)
+
+
+def _cmd_generate(args: list[str]) -> None:
+    if len(args) > 1:
+        msg = "generate takes at most one argument: [seconds]"
+        raise ValueError(msg)
+    print(generate(seconds=float(args[0])) if args else generate())
+
+
+def _cmd_solve(args: list[str]) -> None:
+    if len(args) != 1:
+        msg = "solve takes exactly one argument: <challenge>"
+        raise ValueError(msg)
+    print(solve(args[0]))
+
+
+def _cmd_validate(args: list[str]) -> int:
+    if len(args) != 2:
+        msg = "validate takes exactly two arguments: <challenge> <solution>"
+        raise ValueError(msg)
+    try:
+        validate(args[0], args[1])
+    except ValueError as e:
+        print(e, file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_js(args: list[str]) -> None:
+    if len(args) > 1:
+        msg = "js takes at most one argument: [filename]"
+        raise ValueError(msg)
+    if args:
+        Path(args[0]).write_text(js, encoding="utf-8")
+    else:
+        print(js)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the easypow CLI; return exit code."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in ("-h", "--help"):
+        print(USAGE, file=sys.stderr if not args else sys.stdout)
+        return 0 if args else 2
+    try:
+        handler = {
+            "generate": _cmd_generate,
+            "solve": _cmd_solve,
+            "validate": _cmd_validate,
+            "js": _cmd_js,
+        }[_match(args.pop(0))]
+        result = handler(args)
+    except ValueError as e:
+        print(e, file=sys.stderr)
+        return 2
+    return result or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

easypow-0.1.0/easypow/easypow.js

@@ -0,0 +1,19 @@
+async function solve(challenge, signal) {
+  const B64URL = { alphabet: 'base64url', omitPadding: true }
+  const c = Uint8Array.fromBase64(challenge, B64URL)
+  const key = await crypto.subtle.importKey('raw', c, 'PBKDF2', false, ['deriveBits'])
+  const salt = new Uint32Array(1)
+  const args = { name: 'PBKDF2', salt, iterations: 1 << (c[1] & 0xF), hash: 'SHA-512' }
+  const mask = (1 << (c[1] >> 4)) - 1
+  const fragments = []
+  for (let w=c[0]; w-->0;) {
+    if (signal?.aborted) throw new DOMException('PoW operation aborted', 'AbortError')
+    do {
+      ++salt[0]
+    } while (new Uint32Array(await crypto.subtle.deriveBits(args, key, 32))[0] & mask)
+    fragments.push(new Uint8Array(salt.buffer).toBase64(B64URL).replace(/A+$/, ''))
+  }
+  return fragments.join('.')
+}
+
+export { solve, solve as default }

easypow-0.1.0/easypow/pow.py

@@ -0,0 +1,67 @@
+"""Proof-of-Work captcha using PBKDF2-SHA512.
+
+Challenges are 9 bytes — work byte w, difficulty byte (high nibble:
+zero bits z; low nibble: PBKDF2 iteration exponent n), 7 random
+bytes — as 12-char base64url. Solutions are `w` dot-separated 4-byte
+nonces, each base64url (6 chars max) with trailing 'A' zero-bit chars
+stripped.
+"""
+
+import hashlib
+import secrets
+
+import base64url
+
+# (max work units, zero bits z, 1<<n iterations, work shift); 1 unit = 0.1s
+TIERS = [
+    (31, 11, 7, 0),
+    (127, 12, 7, 1),
+    (511, 13, 7, 2),
+    (2047, 14, 7, 3),
+    (4095, 15, 7, 4),
+]
+
+
+def generate(seconds: float = 1.0) -> str:
+    """Generate a challenge taking about `seconds` to solve (0.1 to 410)."""
+    units = max(0, round(seconds * 10))
+    _, z, n, shift = next((t for t in TIERS if units <= t[0]), TIERS[-1])
+    w = min(units >> shift, 255)
+    return base64url.enc(bytes([w, z << 4 | n]) + secrets.token_bytes(7))
+
+
+def solve(challenge: str) -> str:
+    """Solve a challenge, takes some time."""
+    c, w, mask, iterations = _decode(challenge)
+    fragments = []
+    n = 0
+    for _ in range(w):
+        while True:
+            n += 1
+            nonce = n.to_bytes(4, "little")
+            digest = hashlib.pbkdf2_hmac("sha512", c, nonce, iterations, 2)
+            if not int.from_bytes(digest[:4], "little") & mask:
+                fragments.append(base64url.enc(nonce).rstrip("A"))
+                break
+    return ".".join(fragments)
+
+
+def validate(challenge: str, solution: str) -> None:
+    """Validate a solution; raise ValueError if invalid."""
+    c, w, mask, iterations = _decode(challenge)
+    fragments = solution.split(".") if solution else []
+    if len(fragments) != w or any(len(f) > 6 for f in fragments):
+        msg = "Malformed easypow solution"
+        raise ValueError(msg)
+    for fragment in fragments:
+        nonce = base64url.dec(fragment.ljust(6, "A"))
+        digest = hashlib.pbkdf2_hmac("sha512", c, nonce, iterations, 2)
+        if int.from_bytes(digest[:4], "little") & mask:
+            msg = "Invalid easypow solution"
+            raise ValueError(msg)
+
+
+def _decode(challenge: str) -> tuple[bytes, int, int, int]:
+    c = base64url.dec(challenge)
+    w, diff = c[0], c[1]
+    return c, w, (1 << (diff >> 4)) - 1, 1 << (diff & 0xF)

easypow-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = [
+    "hatchling>=1.25.0",
+    "hatch-vcs>=0.4.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "easypow"
+dynamic = ["version"]
+description = "Antibot Proof-of-Work protection to verify browsers on web apps."
+authors = [
+    { name = "Leo Vasanko" },
+]
+keywords = ["proof-of-work", "antibot", "web-security"]
+readme = "README.md"
+license = "MIT OR Unlicense"
+requires-python = ">=3.11"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security",
+]
+dependencies = [
+    "base64url>=1.1.1",
+]
+
+[project.urls]
+Repository = "https://git.zi.fi/LeoVasanko/easypow"
+Issues = "https://github.com/LeoVasanko/easypow"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["easypow"]
+
+[tool.ruff]
+extend-exclude = ["*.md"]
+
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # Conflicts with the formatter
+    "CPY",   # No copyright notices
+    "D107",  # Missing docstring in __init__
+    "D203",  # incompatible with D211
+    "D213",  # incompatible with D212
+    "PLR2004",  # Magic values are clear enough in this domain
+]
+
+[tool.ruff.lint.per-file-ignores]
+"easypow/__main__.py" = ["T201"]  # CLI prints to stdout/stderr by design
+"tests/**" = ["D", "INP", "PLR2004", "S101", "S603"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

easypow-0.1.0/tests/test_cross_language.py

@@ -0,0 +1,75 @@
+"""Cross-language tests: the bundled JS solver and the Python validator must agree.
+
+These tests execute the actual bundled easypow.js with Node.js, guarding
+against the two implementations drifting apart (e.g. mismatched masks).
+Skipped when node is not available.
+"""
+
+import json
+import secrets
+import shutil
+import subprocess
+from importlib.resources import files
+
+import base64url
+import pytest
+
+from easypow import generate, solve, validate
+from easypow.pow import _decode
+
+NODE = shutil.which("node")
+SOLVER_PATH = files("easypow").joinpath("easypow.js")
+
+pytestmark = pytest.mark.skipif(NODE is None, reason="node is not available")
+
+
+def _run_node(script: str) -> str:
+    result = subprocess.run(
+        [NODE, "--input-type=module", "-e", script],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def _js_solves(challenge: str) -> None:
+    script = (
+        f"import solve from {json.dumps(str(SOLVER_PATH))}\n"
+        f"console.log(await solve({json.dumps(challenge)}))"
+    )
+    validate(challenge, _run_node(script).splitlines()[-1])
+
+
+def test_js_solution_validates_in_python() -> None:
+    _js_solves(generate(seconds=0.2))
+
+
+def test_js_solution_validates_in_python_custom_params() -> None:
+    _js_solves(base64url.enc(bytes([2, 9 << 4 | 6]) + secrets.token_bytes(7)))
+
+
+def test_python_solution_validates_in_js() -> None:
+    challenge = generate(seconds=0.2)
+    _, _, mask, iterations = _decode(challenge)
+    script = f"""
+const B64URL = {{ alphabet: 'base64url', omitPadding: true }}
+const challenge = Uint8Array.fromBase64({json.dumps(challenge)}, B64URL)
+const key = await crypto.subtle.importKey(
+  'raw', challenge, 'PBKDF2', false, ['deriveBits']
+)
+const args = {{
+  name: 'PBKDF2', salt: null, hash: 'SHA-512', iterations: {iterations}
+}}
+for (const fragment of {json.dumps(solve(challenge))}.split('.')) {{
+  const nonce = Uint8Array.fromBase64(fragment.padEnd(6, 'A'), B64URL)
+  const result = new Uint32Array(await crypto.subtle.deriveBits(
+    {{ ...args, salt: nonce }}, key, 32
+  ))
+  if (result[0] & {mask}) {{
+    console.error('nonce failed mask check')
+    process.exit(1)
+  }}
+}}
+"""
+    _run_node(script)

easypow-0.1.0/tests/test_pow.py

@@ -0,0 +1,101 @@
+"""Unit tests for the proof-of-work utilities."""
+
+import secrets
+
+import base64url
+import pytest
+
+from easypow import generate, js, solve, validate
+from easypow.pow import _decode
+
+
+def test_generate_is_12_char_b64url() -> None:
+    encoded = generate()
+    assert len(encoded) == 12
+    assert "=" not in encoded
+    assert len(base64url.dec(encoded)) == 9
+
+
+def test_generate_embeds_work() -> None:
+    assert _decode(generate(seconds=0.7))[1] == 7
+
+
+def test_generate_clamps_to_max() -> None:
+    assert _decode(generate(seconds=10000))[1:] == (255, 0x7FFF, 128)
+
+
+def test_zero_work_validates_trivially() -> None:
+    challenge = generate(seconds=0)
+    assert _decode(challenge)[1] == 0
+    assert solve(challenge) == ""
+    validate(challenge, "")
+
+
+def test_zero_zero_bits_validates_trivially() -> None:
+    # Hand-crafted: zero-bits nibble 0 means mask 0, any nonce passes.
+    challenge = base64url.enc(b"\x01\x00" + secrets.token_bytes(7))
+    assert _decode(challenge)[2] == 0
+    validate(challenge, solve(challenge))
+
+
+@pytest.mark.parametrize(
+    ("work", "embedded", "zero_bits"),
+    [
+        (1, 1, 11),
+        (31, 31, 11),
+        (32, 16, 12),
+        (127, 63, 12),
+        (128, 32, 13),
+        (511, 127, 13),
+        (512, 64, 14),
+        (2047, 255, 14),
+        (2048, 128, 15),
+        (4095, 255, 15),
+    ],
+)
+def test_difficulty_tiers(work: int, embedded: int, zero_bits: int) -> None:
+    _, w, mask, _ = _decode(generate(seconds=work / 10))
+    assert w == embedded
+    assert mask == (1 << zero_bits) - 1
+
+
+def test_decode_default() -> None:
+    assert _decode(generate())[1:] == (10, 0x7FF, 128)
+
+
+def test_decode_custom() -> None:
+    challenge = bytes([2, 9 << 4 | 6]) + secrets.token_bytes(7)
+    assert _decode(base64url.enc(challenge))[1:] == (2, 0x1FF, 64)
+
+
+def test_solve_format_strips_trailing_a_chars() -> None:
+    solution = solve(generate(seconds=0.2))
+    assert "." in solution
+    assert "=" not in solution
+
+
+def test_validate_valid() -> None:
+    challenge = generate(seconds=0.2)
+    validate(challenge, solve(challenge))
+
+
+def test_validate_invalid_solution() -> None:
+    challenge = generate(seconds=0.2)
+    with pytest.raises(ValueError, match="Invalid easypow solution"):
+        validate(challenge, "AA.AA")
+
+
+def test_validate_wrong_work() -> None:
+    # Solution valid for work=1 does not satisfy a work=2 challenge.
+    solution = solve(generate(seconds=0.1))
+    with pytest.raises(ValueError, match="Malformed easypow solution"):
+        validate(generate(seconds=0.2), solution)
+
+
+def test_validate_fragment_too_long() -> None:
+    with pytest.raises(ValueError, match="Malformed easypow solution"):
+        validate(generate(seconds=0.2), "AQAAAAA.AQ")  # First fragment is 7 chars
+
+
+def test_js_bundled() -> None:
+    assert "export { solve, solve as default }" in js