bot403 0.1.0__py3-none-any.whl

bot403/__init__.py

@@ -0,0 +1,79 @@
+"""Check Bot403 tokens on your server: post the token, or the whole
+submitted form, to POST /api/v1/verify. Standard library only."""
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+__all__ = ["Bot403", "Bot403Error", "Result", "FIELD", "DEFAULT_BASE_URL"]
+__version__ = "0.1.0"
+
+FIELD = "_bot403"
+DEFAULT_BASE_URL = "https://bot403.com"
+
+
+@dataclass
+class Result:
+    """The verify answer. ok is False with a reason: invalid, expired, replay,
+    wrong_site, honeypot, automation, or quota (HTTP 402, capped month only)."""
+
+    ok: bool
+    site: str = ""
+    reason: Optional[str] = None
+    solved_at: Optional[str] = None
+    origin: Optional[str] = None
+    difficulty: Optional[str] = None
+    automation: Optional[dict] = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+class Bot403Error(Exception):
+    """The API refused the request as a whole (401, 413, 429, ...), or the
+    network failed (status 0, code "network")."""
+
+    def __init__(self, message: str, status: int, code: str):
+        super().__init__(message)
+        self.status, self.code = status, code
+
+
+class Bot403:
+    def __init__(self, secret_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 10):
+        self._key = secret_key or os.environ.get("BOT403_SECRET_KEY", "")
+        if not self._key or self._key.startswith("pk_"):
+            raise ValueError("bot403: pass the site's secret key (sk_live_...) or set BOT403_SECRET_KEY")
+        self._url, self._timeout = base_url.rstrip("/") + "/api/v1/verify", timeout
+
+    def verify(self, token: Optional[str]) -> Result:
+        """Checks one token."""
+        return self._post(json.dumps({"solution": token or ""}).encode(), "application/json")
+
+    def verify_form(self, form: Mapping[str, Any]) -> Result:
+        """Posts the whole submitted form, so the site's honeypot is checked too."""
+        pairs = [(k, v[0] if isinstance(v, (list, tuple)) else v) for k, v in form.items()]
+        body = urllib.parse.urlencode([(k, v) for k, v in pairs if isinstance(v, str)]).encode()
+        return self._post(body, "application/x-www-form-urlencoded")
+
+    def _post(self, body: bytes, content_type: str) -> Result:
+        headers = {"Authorization": "Bearer " + self._key, "Content-Type": content_type, "Accept": "application/json"}
+        req = urllib.request.Request(self._url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                status, data = res.status, res.read()
+        except urllib.error.HTTPError as e:
+            status, data = e.code, e.read()
+        except OSError as e:
+            raise Bot403Error("bot403: verify failed: %s" % e, 0, "network") from e
+        try:
+            j = json.loads(data or b"{}")
+        except ValueError:
+            j = {}
+        # 402 is a normal answer: the quota is used up in a capped month.
+        if status in (200, 402) and "ok" in j:
+            keys = ("site", "reason", "solved_at", "origin", "difficulty", "automation")
+            return Result(ok=bool(j["ok"]), **{k: j.get(k) for k in keys if k in j}, raw=j)
+        code = j.get("reason") or j.get("error") or "http_%d" % status
+        raise Bot403Error("bot403: %s" % j.get("message", "HTTP %d" % status), status, code)

bot403-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: bot403
+Version: 0.1.0
+Summary: Bot403 for Python servers: check the proof-of-work token a protected HTML form sends. Standard library only.
+Project-URL: Homepage, https://bot403.com
+Project-URL: Documentation, https://bot403.com/docs/verify
+Project-URL: Source, https://github.com/zaharystoyanovlabs/bot403-python
+Author-email: Zahary Stoyanov <hello@bot403.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: altcha,bot-protection,bot403,captcha,forms,proof-of-work,spam
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bot403 for Python
+
+Bot403 is an invisible bot shield for HTML forms: one script tag makes the browser solve a small proof of work, and your server checks it with one call. This package is that call for Python. It uses only the standard library. The free plan covers 5,000 checks a month.
+
+## Install
+
+```sh
+pip install bot403
+```
+
+## Set up
+
+1. Create a site at [bot403.com](https://bot403.com). You get a public key (`pk_live_…`) and a secret key (`sk_live_…`).
+2. Add the script tag to the page with the form, before `</body>`:
+
+   ```html
+   <script src="https://bot403.com/v1/bot403.js" data-bot403-key="pk_live_…" defer></script>
+   ```
+
+3. Put the secret key in the environment of your server, never in a page or in Git:
+
+   ```sh
+   BOT403_SECRET_KEY=sk_live_…
+   ```
+
+4. Check the form on submit (Flask):
+
+   ```python
+   from bot403 import Bot403, Bot403Error
+   from flask import Flask, abort, request
+
+   app = Flask(__name__)
+   bot403 = Bot403()  # reads BOT403_SECRET_KEY
+
+   @app.post("/contact")
+   def contact():
+       try:
+           # Post the whole form: Bot403 reads the _bot403 field and the honeypot field.
+           result = bot403.verify_form(request.form)
+       except Bot403Error as e:
+           if e.status != 0:
+               raise
+           result = None  # Bot403 did not answer: let the form through
+       # Refuse when ok is false, except for reason "quota".
+       if result and not result.ok and result.reason != "quota":
+           abort(400)
+       return "Thanks."
+   ```
+
+   Django: `bot403.verify_form(request.POST)`. With `fetch` and JSON, send the token alone: `bot403.verify(token)`.
+
+## Answers
+
+`verify` and `verify_form` return a `Result`. A token that fails is not an exception.
+
+| `result.ok` / `result.reason` | Meaning | What to do |
+|---|---|---|
+| `True` | A browser solved the puzzle for this site. The token was not used before. | Accept. |
+| `invalid` | The token is missing, damaged, or wrong. | Reject. |
+| `expired` | The challenge is older than the site's expiry (default 10 minutes). | Reject. Ask the visitor to send again. |
+| `replay` | The token was used before. | Reject. |
+| `wrong_site` | The token belongs to a different site. | Reject. Check the keys. |
+| `honeypot` | The hidden honeypot field had a value. | Reject, or show a fake success. |
+| `quota` (HTTP 402) | Only in a capped month, after two calendar months over the plan in a row. The token is not used up. | Your choice. The example lets the form through. |
+
+`Bot403Error` means the request failed as a whole. `e.status` is the HTTP status (401 wrong key, 429 too many verify calls a minute, 413 body over 64 KB), or 0 when the network failed (`e.code == "network"`). Decide what your server does when Bot403 does not answer. The example lets the form through.
+
+Options: `Bot403(secret_key=None, base_url="https://bot403.com", timeout=10)`.
+
+All answers and reasons: [bot403.com/docs/verify](https://bot403.com/docs/verify). API reference: [bot403.com/docs/api](https://bot403.com/docs/api).
+
+## Test
+
+The tests run against a local fake of the API. They make no network calls.
+
+```sh
+uv run --with pytest --with . python -m pytest -q tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bot403-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+bot403/__init__.py,sha256=IBqJ9rLvWXoJpc2iqE8QYDNy-0QPQ5Mqt6-DGDSxe5Y,3434
+bot403/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bot403-0.1.0.dist-info/METADATA,sha256=lEIemCYAj3ndUG-FkepCQh3i1j1XMNYhep0gS1U5ztk,3944
+bot403-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bot403-0.1.0.dist-info/licenses/LICENSE,sha256=b6gvkN_anPXSjCwxsHxuAc59PUUYlpgOb2yrnNVUS7k,1072
+bot403-0.1.0.dist-info/RECORD,,

bot403-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

bot403-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Stoyanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.