capwx 0.1.0__py3-none-any.whl

capwx/__init__.py

@@ -0,0 +1,52 @@
+"""capwx: a Python server for the Cap CAPTCHA widget (HashWX, sha256-pow, instrumentation).
+
+Importing ``capwx`` never imports wasmtime. The HashWX engine loads on first use, or eagerly via
+:func:`hashwx_ready` at application startup.
+"""
+
+from __future__ import annotations
+
+from capwx.challenge import (
+    RedeemResult,
+    acreate_challenge,
+    aredeem,
+    create_challenge,
+    redeem,
+    set_event_callback,
+)
+from capwx.config import CapConfig, InstrumentationOptions
+from capwx.errors import CapwxError, Reason
+from capwx.stores.memory import MemoryStore
+from capwx.tokens import avalidate_token, siteverify, validate_token
+
+__version__ = "0.1.0"
+
+
+def hashwx_ready(wasm_path: str | None = None) -> None:
+    """Force HashWX engine initialisation (imports wasmtime). Call at application startup.
+
+    Raises ``CapwxError`` if the vendored wasm is missing, tampered with, or cannot be instantiated.
+    """
+    from capwx.protocols.hashwx import hashwx_ready as _ready
+
+    _ready(wasm_path)
+
+
+__all__ = [
+    "CapConfig",
+    "CapwxError",
+    "InstrumentationOptions",
+    "MemoryStore",
+    "Reason",
+    "RedeemResult",
+    "__version__",
+    "acreate_challenge",
+    "aredeem",
+    "avalidate_token",
+    "create_challenge",
+    "hashwx_ready",
+    "redeem",
+    "set_event_callback",
+    "siteverify",
+    "validate_token",
+]

capwx/_crypto.py

@@ -0,0 +1,127 @@
+"""capwx._crypto: b64url, JWT HS256, AES-GCM and sha256 helpers.
+
+Byte-compatible with upstream ``core/src/crypto.js`` (capjs-core 0.1.5):
+tokens minted here validate in Node and vice versa.
+
+Client-supplied input (tokens, blobs) never raises: bad input yields ``None``.
+Programmer errors (wrong secret type) still raise.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import re
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from capwx._types import JsonDict, as_json_dict
+
+_B64URL_RE = re.compile(r"[A-Za-z0-9_-]*")
+_GCM_IV_LEN = 12
+_GCM_TAG_LEN = 16
+
+
+def random_hex(nbytes: int) -> str:  # JS randomHex(n): n bytes -> 2n hex chars
+    return os.urandom(nbytes).hex()
+
+
+def sha256_hex(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def b64url(data: bytes) -> str:  # Node "base64url": NO padding
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(s: object) -> bytes:
+    """Strict base64url decode (no padding required). Raises ValueError on bad input."""
+    if not isinstance(s, str) or _B64URL_RE.fullmatch(s) is None or len(s) % 4 == 1:
+        raise ValueError("invalid base64url")
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+_JWT_HEADER_B64 = b64url(b'{"alg":"HS256","typ":"JWT"}')  # exact bytes, do not re-serialise
+
+
+def _key(secret: str | bytes) -> bytes:
+    return secret.encode("utf-8") if isinstance(secret, str) else secret
+
+
+def jwt_sign(payload: JsonDict, secret: str | bytes) -> str:
+    body = b64url(json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8"))
+    sig_input = f"{_JWT_HEADER_B64}.{body}"
+    sig = hmac.new(_key(secret), sig_input.encode("ascii"), hashlib.sha256).digest()
+    return f"{sig_input}.{b64url(sig)}"
+
+
+def jwt_verify(token: object, secret: str | bytes) -> JsonDict | None:
+    """Return the payload dict if the HS256 token is valid, else None. Never raises on bad input."""
+    key = _key(secret)  # programmer error (wrong type) is allowed to raise
+    if not isinstance(token, str) or not token:
+        return None
+    first = token.find(".")
+    last = token.rfind(".")
+    # Exactly two dots, and the first one is not at index 0 (empty header is invalid).
+    if first < 1 or first == last or token.find(".", first + 1) != last:
+        return None
+    try:
+        expected = hmac.new(key, token[:last].encode("utf-8"), hashlib.sha256).digest()
+        actual = b64url_decode(token[last + 1 :])
+    except (ValueError, UnicodeError):
+        return None
+    if not hmac.compare_digest(expected, actual):
+        return None
+    try:
+        payload: Any = json.loads(b64url_decode(token[first + 1 : last]).decode("utf-8"))
+    except (ValueError, UnicodeError, RecursionError):
+        return None
+    return as_json_dict(payload)
+
+
+def jwt_sig_hex(token: object) -> str | None:  # hex of the decoded signature (replay key)
+    """Hex of the decoded signature segment, or None. Never raises on bad input."""
+    if not isinstance(token, str) or not token:
+        return None
+    last = token.rfind(".")
+    if last == -1:
+        return None
+    try:
+        return b64url_decode(token[last + 1 :]).hex()
+    except ValueError:
+        return None
+
+
+def _derive_gcm_key(secret: str | bytes, info: str) -> bytes:
+    return hmac.new(_key(secret), info.encode("utf-8"), hashlib.sha256).digest()  # 32 bytes
+
+
+def encrypt_gcm(data: object, secret: str | bytes, info: str = "cap:enc-v1") -> str:
+    key = _derive_gcm_key(secret, info)
+    iv = os.urandom(_GCM_IV_LEN)
+    plaintext = json.dumps(data, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    # AESGCM.encrypt returns ciphertext || tag; Node's blob layout is iv || tag || ciphertext.
+    ct_and_tag = AESGCM(key).encrypt(iv, plaintext, None)
+    ct, tag = ct_and_tag[:-_GCM_TAG_LEN], ct_and_tag[-_GCM_TAG_LEN:]
+    return b64url(iv + tag + ct)
+
+
+def decrypt_gcm(blob: object, secret: str | bytes, info: str = "cap:enc-v1") -> Any | None:
+    """Decrypt a blob from encrypt_gcm / Node encryptGcm. Returns the JSON value, or None."""
+    key = _derive_gcm_key(secret, info)  # programmer error (wrong type) may raise
+    try:
+        buf = b64url_decode(blob)
+        if len(buf) < _GCM_IV_LEN + _GCM_TAG_LEN:
+            return None
+        iv = buf[:_GCM_IV_LEN]
+        tag = buf[_GCM_IV_LEN : _GCM_IV_LEN + _GCM_TAG_LEN]
+        ct = buf[_GCM_IV_LEN + _GCM_TAG_LEN :]
+        # cryptography expects ciphertext || tag, so reorder the Node layout.
+        plaintext = AESGCM(key).decrypt(iv, ct + tag, None)
+        value: Any = json.loads(plaintext.decode("utf-8"))
+        return value
+    except (ValueError, UnicodeError, InvalidTag, RecursionError):
+        return None

capwx/_jsint.py

@@ -0,0 +1,68 @@
+"""JavaScript integer semantics. Every function here mirrors a JS operator.
+
+Pitfall list:
+- Python ``%`` on negatives differs from JS -> always ``js_rem``.
+- Python ``bool`` is an ``int`` -> every "is this a number" check must exclude ``bool``.
+- ``charCodeAt`` is UTF-16 code units, not code points -> ``utf16_units``.
+"""
+
+import math
+
+
+def to_int32(n: int) -> int:  # JS: n | 0   (for integer n)
+    n &= 0xFFFFFFFF
+    return n - (1 << 32) if n & 0x80000000 else n
+
+
+def to_uint32(n: int) -> int:  # JS: n >>> 0
+    return n & 0xFFFFFFFF
+
+
+def js_shl(a: int, k: int) -> int:  # JS: a << k
+    return to_int32(to_int32(a) << (k & 31))
+
+
+def js_sar(a: int, k: int) -> int:  # JS: a >> k  (arithmetic)
+    return to_int32(a) >> (k & 31)
+
+
+def js_shr(a: int, k: int) -> int:  # JS: a >>> k (logical)
+    return to_uint32(a) >> (k & 31)
+
+
+def js_xor(a: int, b: int) -> int:  # JS: a ^ b
+    return to_int32(to_int32(a) ^ to_int32(b))
+
+
+def js_and(a: int, b: int) -> int:
+    return to_int32(to_int32(a) & to_int32(b))
+
+
+def js_or(a: int, b: int) -> int:
+    return to_int32(to_int32(a) | to_int32(b))
+
+
+def js_not(a: int) -> int:  # JS: ~a
+    return to_int32(~to_int32(a))
+
+
+def js_rem(a: int, b: int) -> int:  # JS: a % b  (sign follows dividend!)
+    return int(math.fmod(a, b))
+
+
+def utf16_units(s: str) -> list[int]:  # JS: s.charCodeAt(i) for each i
+    b = s.encode("utf-16-le")
+    return [int.from_bytes(b[i : i + 2], "little") for i in range(0, len(b), 2)]
+
+
+def js_number_str(n: int) -> str:  # JS: String(n) for safe integers
+    return str(n)
+
+
+def is_js_number(x: object) -> bool:  # JS: typeof x === "number" && isFinite(x)
+    if not isinstance(x, (int, float)) or isinstance(x, bool):
+        return False
+    try:
+        return math.isfinite(x)
+    except OverflowError:  # int beyond double range acts as Infinity in JS
+        return False

capwx/_types.py

@@ -0,0 +1,35 @@
+"""capwx._types: shared typing helpers for the JSON-shaped payloads.
+
+Challenge payloads, solutions and decrypted claims are JSON values whose contents are checked
+at runtime. They are typed ``Any`` at the boundary and narrowed with the helpers below, which
+cast once after an ``isinstance`` check, instead of leaving bare ``dict`` / ``list`` types behind.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeAlias, cast
+
+JsonDict: TypeAlias = dict[str, Any]
+JsonList: TypeAlias = list[Any]
+
+
+def as_json_dict(value: object) -> JsonDict | None:
+    """Return ``value`` as a JSON object (``dict``) or None. Never raises."""
+    if not isinstance(value, dict):
+        return None
+    return cast(JsonDict, value)
+
+
+def as_mapping(value: object) -> Mapping[Any, Any] | None:
+    """Return ``value`` as a mapping (dict-like) or None. Never raises."""
+    if not isinstance(value, Mapping):
+        return None
+    return cast("Mapping[Any, Any]", value)
+
+
+def as_json_list(value: object) -> JsonList | None:
+    """Return ``value`` as a JSON array (``list``) or None. Never raises."""
+    if not isinstance(value, list):
+        return None
+    return cast(JsonList, value)

capwx/_vendor/__init__.py

@@ -0,0 +1 @@
+"""capwx._vendor: vendored third-party binary assets."""

capwx/_vendor/hashwx/COMMIT

@@ -0,0 +1 @@
+74b567a31276a4c5d7cb232a5b7639467f49f961

capwx/_vendor/hashwx/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

capwx/_vendor/hashwx/SHA256

@@ -0,0 +1 @@
+b1a0dbb3ef444d3c7069e0a5e0a0273ffa4cf8fef62cbbe43761c02f7cd6aff5  hashwx.wasm

capwx/_vendor/hashwx/__init__.py

@@ -0,0 +1 @@
+"""capwx._vendor.hashwx: vendored HashWX wasm (LGPL-3.0), loaded via importlib.resources."""