easypow 0.1.0__py3-none-any.whl

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/__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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+easypow/__init__.py,sha256=omoJVaAFz6UFe3z1qR4Jeq7D5I0h6_3A-g4-hvBinis,361
+easypow/__main__.py,sha256=nDJ2mlBEkxYMHLOuu0zIeVV4TooprD-1eiVnzIjwt0g,2559
+easypow/easypow.js,sha256=CTaEw5zEuqEyiqxt7lyI2cOz0N6cjyzEbZZJousjKoI,810
+easypow/pow.py,sha256=HMwgUXAfJHyeaPCxgeRxofLSreXIK0zg9eSBRnPpMlI,2277
+easypow-0.1.0.dist-info/METADATA,sha256=dcUWJ7b63J2ypGTlgq1qOEp-qqQwMj_WKiOTLivm3o8,7395
+easypow-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+easypow-0.1.0.dist-info/RECORD,,

easypow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any