valgix-humanpass 0.1.0__tar.gz

valgix_humanpass-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

valgix_humanpass-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: valgix-humanpass
+Version: 0.1.0
+Summary: Official Python server SDK for Valgix HumanPass.
+Project-URL: Documentation, https://docs.valgix.com/humanpass/
+Project-URL: Repository, https://github.com/valgixcenter/humanpass-python
+Project-URL: Issues, https://github.com/valgixcenter/humanpass-python/issues
+Author: Valgix
+Keywords: captcha,humanpass,security,valgix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HumanPass for Python
+
+Official Python server SDK for [Valgix HumanPass](https://docs.valgix.com/humanpass/).
+
+```bash
+pip install valgix-humanpass
+```
+
+```python
+import os
+from humanpass import HumanPass
+
+humanpass = HumanPass(secret=os.environ["HUMANPASS_SECRET_KEY"])
+
+result = humanpass.verify(
+    response=request.form["humanpass-response"],
+    expected_action="signup",
+    expected_hostname="example.com",
+)
+
+if not result.success:
+    # Reject the protected operation.
+    pass
+```
+
+Keep the secret key on your server. Browser applications use the HumanPass widget and a public site key instead.

valgix_humanpass-0.1.0/README.md

@@ -0,0 +1,26 @@
+# HumanPass for Python
+
+Official Python server SDK for [Valgix HumanPass](https://docs.valgix.com/humanpass/).
+
+```bash
+pip install valgix-humanpass
+```
+
+```python
+import os
+from humanpass import HumanPass
+
+humanpass = HumanPass(secret=os.environ["HUMANPASS_SECRET_KEY"])
+
+result = humanpass.verify(
+    response=request.form["humanpass-response"],
+    expected_action="signup",
+    expected_hostname="example.com",
+)
+
+if not result.success:
+    # Reject the protected operation.
+    pass
+```
+
+Keep the secret key on your server. Browser applications use the HumanPass widget and a public site key instead.

valgix_humanpass-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "valgix-humanpass"
+version = "0.1.0"
+description = "Official Python server SDK for Valgix HumanPass."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Valgix" }]
+keywords = ["humanpass", "captcha", "security", "valgix"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://docs.valgix.com/humanpass/"
+Repository = "https://github.com/valgixcenter/humanpass-python"
+Issues = "https://github.com/valgixcenter/humanpass-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/humanpass"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+  "build>=1.2",
+  "twine>=6.1",
+]

valgix_humanpass-0.1.0/src/humanpass/__init__.py

@@ -0,0 +1,21 @@
+from .client import HumanPass
+from .errors import (
+    HumanPassApiError,
+    HumanPassConfigurationError,
+    HumanPassError,
+    HumanPassTransportError,
+)
+from .models import SiteverifyFailure, SiteverifyResult, SiteverifySuccess
+
+__all__ = [
+    "HumanPass",
+    "HumanPassApiError",
+    "HumanPassConfigurationError",
+    "HumanPassError",
+    "HumanPassTransportError",
+    "SiteverifyFailure",
+    "SiteverifyResult",
+    "SiteverifySuccess",
+]
+
+__version__ = "0.1.0"

valgix_humanpass-0.1.0/src/humanpass/client.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import json
+import re
+import socket
+from collections.abc import Callable
+from typing import Any, Protocol, cast
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+from .errors import (
+    HumanPassApiError,
+    HumanPassConfigurationError,
+    HumanPassTransportError,
+)
+from .models import (
+    SITEVERIFY_ERROR_CODES,
+    SiteverifyErrorCode,
+    SiteverifyFailure,
+    SiteverifyResult,
+    SiteverifySuccess,
+)
+
+DEFAULT_BASE_URL = "https://humanpass.valgix.com"
+DEFAULT_TIMEOUT_SECONDS = 5.0
+MAX_RESPONSE_BYTES = 64 * 1024
+SECRET_PATTERN = re.compile(r"^hp_secret_(?:live|test)_[A-Za-z0-9_-]{16,}$")
+RESPONSE_PATTERN = re.compile(r"^hp_response_[A-Za-z0-9._~-]{16,}$")
+HOSTNAME_PATTERN = re.compile(
+    r"^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*"
+    r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
+)
+
+
+class HttpResponse(Protocol):
+    status: int
+    headers: Any
+
+    def read(self, amount: int = -1) -> bytes: ...
+
+    def __enter__(self) -> HttpResponse: ...
+
+    def __exit__(self, *args: object) -> None: ...
+
+
+Transport = Callable[[Request, float], HttpResponse]
+
+
+def _default_transport(request: Request, timeout: float) -> HttpResponse:
+    return cast(HttpResponse, urlopen(request, timeout=timeout))
+
+
+def _normalize_base_url(value: str) -> str:
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"https", "http"} or not parsed.hostname:
+        raise HumanPassConfigurationError("HumanPass base_url must be a valid HTTP URL.")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise HumanPassConfigurationError("HumanPass base_url is not allowed.")
+    if parsed.scheme == "http" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"}:
+        raise HumanPassConfigurationError(
+            "HumanPass base_url must use HTTPS outside local development."
+        )
+    return urlunsplit((parsed.scheme, parsed.netloc, parsed.path.rstrip("/"), "", ""))
+
+
+def _normalize_hostname(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower().rstrip(".")
+    if not HOSTNAME_PATTERN.fullmatch(normalized):
+        raise HumanPassConfigurationError(
+            "expected_hostname must be a valid hostname without a port."
+        )
+    return normalized
+
+
+def _bounded_json(response: HttpResponse) -> dict[str, Any]:
+    raw = response.read(MAX_RESPONSE_BYTES + 1)
+    if len(raw) > MAX_RESPONSE_BYTES:
+        raise ValueError("oversized response")
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError("non-object response")
+    return value
+
+
+def _parse_result(payload: dict[str, Any]) -> SiteverifyResult | None:
+    if payload.get("success") is False:
+        codes = payload.get("error_codes")
+        if not isinstance(codes, list) or not codes or not all(
+            isinstance(code, str) and code in SITEVERIFY_ERROR_CODES for code in codes
+        ):
+            return None
+        request_id = payload.get("request_id")
+        if request_id is not None and not isinstance(request_id, str):
+            return None
+        return SiteverifyFailure(
+            success=False,
+            error_codes=cast(tuple[SiteverifyErrorCode, ...], tuple(codes)),
+            request_id=request_id,
+        )
+
+    required = {
+        "challenge_ts": str,
+        "hostname": str,
+        "action": str,
+        "sitekey": str,
+        "verification_id": str,
+    }
+    if payload.get("success") is not True or any(
+        not isinstance(payload.get(key), expected_type)
+        for key, expected_type in required.items()
+    ):
+        return None
+    environment = payload.get("environment")
+    if environment not in {"live", "test"}:
+        return None
+    return SiteverifySuccess(
+        success=True,
+        challenge_ts=payload["challenge_ts"],
+        hostname=payload["hostname"],
+        action=payload["action"],
+        sitekey=payload["sitekey"],
+        environment=environment,
+        verification_id=payload["verification_id"],
+    )
+
+
+class HumanPass:
+    def __init__(
+        self,
+        *,
+        secret: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        transport: Transport | None = None,
+    ) -> None:
+        if not SECRET_PATTERN.fullmatch(secret):
+            raise HumanPassConfigurationError("HumanPass secret has an invalid format.")
+        if timeout < 0.1:
+            raise HumanPassConfigurationError("HumanPass timeout must be at least 0.1 seconds.")
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = timeout
+        self.__secret = secret
+        self.__transport = transport or _default_transport
+
+    def verify(
+        self,
+        *,
+        response: str,
+        remote_ip: str | None = None,
+        idempotency_key: str | None = None,
+        expected_action: str | None = None,
+        expected_hostname: str | None = None,
+    ) -> SiteverifyResult:
+        if not RESPONSE_PATTERN.fullmatch(response):
+            return SiteverifyFailure(success=False, error_codes=("invalid_input_response",))
+        normalized_hostname = _normalize_hostname(expected_hostname)
+        body = {
+            "response": response,
+            **({"remoteip": remote_ip} if remote_ip else {}),
+            **({"idempotency_key": idempotency_key} if idempotency_key else {}),
+        }
+        request = Request(
+            f"{self.base_url}/v1/siteverify",
+            data=json.dumps(body, separators=(",", ":")).encode(),
+            headers={
+                "Authorization": f"Bearer {self.__secret}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "valgix-humanpass-python/0.1.0",
+            },
+            method="POST",
+        )
+
+        status = 0
+        request_id: str | None = None
+        try:
+            try:
+                result = self.__transport(request, self.timeout)
+                with result as http_response:
+                    status = http_response.status
+                    request_id = http_response.headers.get("X-Request-ID")
+                    payload = _bounded_json(http_response)
+            except HTTPError as error:
+                status = error.code
+                request_id = error.headers.get("X-Request-ID")
+                payload = _bounded_json(cast(HttpResponse, error))
+        except (HTTPError, URLError, TimeoutError, socket.timeout, OSError):
+            raise HumanPassTransportError("HumanPass verification request failed.") from None
+        except (ValueError, json.JSONDecodeError):
+            raise HumanPassApiError(
+                "HumanPass returned an invalid response.",
+                status=status,
+                request_id=request_id,
+            ) from None
+
+        parsed = _parse_result(payload)
+        if isinstance(parsed, SiteverifyFailure):
+            return parsed
+        if status < 200 or status >= 300 or not isinstance(parsed, SiteverifySuccess):
+            code = payload.get("code") if isinstance(payload.get("code"), str) else None
+            raise HumanPassApiError(
+                "HumanPass returned an unexpected response.",
+                status=status,
+                request_id=request_id,
+                code=code,
+            )
+        if expected_action is not None and parsed.action != expected_action:
+            return SiteverifyFailure(
+                success=False,
+                error_codes=("action_mismatch",),
+                request_id=request_id,
+            )
+        if normalized_hostname is not None and parsed.hostname.lower().rstrip(".") != normalized_hostname:
+            return SiteverifyFailure(
+                success=False,
+                error_codes=("hostname_mismatch",),
+                request_id=request_id,
+            )
+        return parsed

valgix_humanpass-0.1.0/src/humanpass/errors.py

@@ -0,0 +1,28 @@
+class HumanPassError(Exception):
+    """Base class for sanitized HumanPass SDK failures."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(message)
+        self.request_id = request_id
+
+
+class HumanPassConfigurationError(HumanPassError):
+    pass
+
+
+class HumanPassTransportError(HumanPassError):
+    pass
+
+
+class HumanPassApiError(HumanPassError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        request_id: str | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message, request_id=request_id)
+        self.status = status
+        self.code = code

valgix_humanpass-0.1.0/src/humanpass/models.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+HumanPassEnvironment: TypeAlias = Literal["live", "test"]
+SiteverifyErrorCode: TypeAlias = Literal[
+    "missing_input_response",
+    "invalid_input_response",
+    "timeout_or_duplicate",
+    "invalid_secret",
+    "site_disabled",
+    "action_mismatch",
+    "hostname_mismatch",
+    "invalid_idempotency_key",
+    "rate_limited",
+    "service_unavailable",
+]
+
+SITEVERIFY_ERROR_CODES: frozenset[str] = frozenset(
+    {
+        "missing_input_response",
+        "invalid_input_response",
+        "timeout_or_duplicate",
+        "invalid_secret",
+        "site_disabled",
+        "action_mismatch",
+        "hostname_mismatch",
+        "invalid_idempotency_key",
+        "rate_limited",
+        "service_unavailable",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SiteverifySuccess:
+    success: Literal[True]
+    challenge_ts: str
+    hostname: str
+    action: str
+    sitekey: str
+    environment: HumanPassEnvironment
+    verification_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class SiteverifyFailure:
+    success: Literal[False]
+    error_codes: tuple[SiteverifyErrorCode, ...]
+    request_id: str | None = None
+
+
+SiteverifyResult: TypeAlias = SiteverifySuccess | SiteverifyFailure

valgix_humanpass-0.1.0/src/humanpass/py.typed

@@ -0,0 +1 @@
+

valgix_humanpass-0.1.0/tests/test_client.py

@@ -0,0 +1,80 @@
+import io
+import json
+import unittest
+
+from humanpass import HumanPass, HumanPassApiError, HumanPassConfigurationError
+
+SECRET = "hp_secret_live_1234567890abcdefgh"
+TOKEN = "hp_response_1234567890abcdefgh"
+SUCCESS = {
+    "success": True,
+    "challenge_ts": "2026-08-22T12:00:00.000Z",
+    "hostname": "example.com",
+    "action": "signup",
+    "sitekey": "hp_site_live_1234567890abcdefgh",
+    "environment": "live",
+    "verification_id": "hpv_1234567890abcdefgh",
+}
+
+
+class Headers(dict[str, str]):
+    def get(self, key: str, default=None):
+        return super().get(key.lower(), default)
+
+
+class Response:
+    def __init__(self, payload, *, status=200):
+        self.status = status
+        self.headers = Headers({"x-request-id": "11111111-1111-4111-8111-111111111111"})
+        self.stream = io.BytesIO(json.dumps(payload).encode())
+
+    def read(self, amount=-1):
+        return self.stream.read(amount)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return None
+
+
+class HumanPassTests(unittest.TestCase):
+    def test_sends_secret_only_in_authorization_header(self):
+        captured = {}
+
+        def transport(request, timeout):
+            captured["request"] = request
+            captured["timeout"] = timeout
+            return Response(SUCCESS)
+
+        result = HumanPass(secret=SECRET, transport=transport).verify(
+            response=TOKEN,
+            remote_ip="203.0.113.10",
+            idempotency_key="signup-attempt-1",
+        )
+        request = captured["request"]
+        self.assertTrue(result.success)
+        self.assertEqual(request.get_header("Authorization"), f"Bearer {SECRET}")
+        self.assertNotIn(SECRET, request.data.decode())
+
+    def test_returns_semantic_action_mismatch(self):
+        client = HumanPass(secret=SECRET, transport=lambda *_: Response(SUCCESS))
+        result = client.verify(response=TOKEN, expected_action="checkout")
+        self.assertFalse(result.success)
+        self.assertEqual(result.error_codes, ("action_mismatch",))
+
+    def test_rejects_insecure_non_loopback_base_url(self):
+        with self.assertRaises(HumanPassConfigurationError):
+            HumanPass(secret=SECRET, base_url="http://example.com")
+
+    def test_rejects_oversized_api_response(self):
+        client = HumanPass(
+            secret=SECRET,
+            transport=lambda *_: Response({"padding": "x" * (70 * 1024)}),
+        )
+        with self.assertRaises(HumanPassApiError):
+            client.verify(response=TOKEN)
+
+
+if __name__ == "__main__":
+    unittest.main()