sentinelsup 0.2.3__tar.gz → 0.2.5__tar.gz

sentinelsup-0.2.5/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: Python SDK
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m unittest discover -s tests -v
+      - name: Build and check distributions
+        if: matrix.python == '3.14'
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+          python -m pip install --no-deps dist/*.whl
+          cd "$RUNNER_TEMP"
+          python -c "from sentinel import Sentinel, SentinelError; assert Sentinel('sk_test_fixture').api_key == 'sk_test_fixture'"

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: sentinelsup
-Version: 0.2.3
-Summary: Maskbreak — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response.
+Version: 0.2.5
+Summary: Official Maskbreak SDK for browser-backed fraud checks and cloud/Tor IP lookups.
 Project-URL: Homepage, https://maskbreak.com
 Project-URL: Documentation, https://maskbreak.com/api
 Project-URL: Repository, https://github.com/sentinelsup/maskbreak-python
@@ -29,7 +29,11 @@ Description-Content-Type: text/markdown
 
 # sentinelsup — Maskbreak Python SDK
 
-Official Python SDK for [Maskbreak](https://maskbreak.com) — a real-time fraud detection API that flags VPNs, residential proxies, antidetect browsers (Kameleo, GoLogin, Multilogin), Tor exit nodes, and AI bots in under 40 ms.
+Official Python SDK for [Maskbreak](https://maskbreak.com). Evaluate SDK-backed
+visits for network and browser risk signals, or look up a public IP for cloud
+range and Tor signals. These are different evidence sources, not interchangeable
+checks. VPN/proxy service names are returned when known; a VPN alone routes to
+review under the default policy, not automatic blocking.
 
 [![PyPI](https://img.shields.io/pypi/v/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
 [![Python versions](https://img.shields.io/pypi/pyversions/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
@@ -37,16 +41,16 @@ Official Python SDK for [Maskbreak](https://maskbreak.com) — a real-time fraud
 
 Zero dependencies — just the standard library. Works with Flask, Django, FastAPI, or bare `urllib`.
 
-## Set up with AI (fastest)
+## Set up with an AI assistant
 
 Using Claude Code, Cursor, Copilot, or any AI coding assistant? Paste this one
 prompt and it wires the whole integration — frontend script, backend check,
 env var, and a test:
 
 > Fetch https://maskbreak.com/integrate.md and follow it to add Maskbreak fraud
-> protection to this app — protect signup, login, and checkout. My API key
-> is sk_live_YOUR_KEY; put it in a SENTINEL_KEY env var, never in
-> client-side code. Then show me how to test it.
+> protection to this app — protect signup, login, and checkout. Read the API key
+> from the server-only MASKBREAK_API_KEY environment variable; I will configure the
+> secret separately. Never put it in client-side code. Show me how to test it.
 
 [`integrate.md`](https://maskbreak.com/integrate.md) is the canonical
 machine-readable integration guide, kept in sync with the live API.
@@ -65,9 +69,12 @@ Python 3.8+. Get a free API key (no credit card) at [maskbreak.com/signup](https
 import os
 from sentinel import Sentinel
 
-s = Sentinel(api_key=os.environ["SENTINEL_KEY"])  # or omit — reads the env var itself
+s = Sentinel(api_key=os.environ["MASKBREAK_API_KEY"])  # or omit — reads the env var itself
 
-result = s.evaluate(token=request.json["sentinelToken"])  # token from the frontend SDK
+result = s.evaluate(
+    token=request.json["sentinelToken"],
+    fingerprint_event_id=request.json.get("fingerprintEventId"),
+)
 
 if result.is_blocked:            # decision == 'block'
     abort(403)
@@ -78,6 +85,14 @@ print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True
 print(result.reasons)         # ['vpn_detected', 'datacenter_asn', ...]
 ```
 
+This is a handler fragment, not a complete signup implementation. Route `review`
+to your verification/review flow; only `allow` is an approval. Keep API keys on
+the server. An unavailable device layer or `raw["degraded"]` is not proof of a
+clean visit; `degraded` describes the network layer only.
+
+Since v0.2.5, `Sentinel()` without a key reads `MASKBREAK_API_KEY`; the older
+`SENTINEL_KEY` and `SENTINEL_API_KEY` names are still read as fallbacks.
+
 Check the signup email against the disposable-domain feed (checked
 transiently, never stored), or look up an arbitrary IP with no browser
 token at all:
@@ -94,7 +109,8 @@ print(info["signals"])              # {'vpn': ..., 'proxied': ..., 'tor': ..., '
 
 ## What you get back
 
-`evaluate()` returns an `EvaluateResult` dataclass:
+`evaluate()` returns an `EvaluateResult` dataclass. The type sketch below uses
+Python 3.10+ annotation syntax for readability; the package minimum stays 3.8:
 
 ```python
 @dataclass
@@ -112,7 +128,7 @@ class EvaluateResult:
     test: bool                  # True for test-token / test-key calls
     raw: dict                   # full upstream response
 
-    is_suspicious: bool         # True if decision != 'allow'
+    is_suspicious: bool         # True for a non-null decision other than 'allow'
     is_blocked: bool            # True if decision == 'block'
 ```
 
@@ -142,7 +158,7 @@ network (VPN/proxy/datacenter) and device (antidetect/bot/tampering):
 
 Forward both fields to your backend with the form submission and pass them to
 `evaluate()` as `token` and `fingerprint_event_id` — without the second one,
-the device-layer signals (antidetect, automation, emulator) never fire. For
+the device-layer signals (antidetect, automation, emulator) are unavailable. For
 fetch/XHR submissions, collect them explicitly:
 
 ```js
@@ -151,20 +167,21 @@ const { token, fingerprintEventId } = await window.Sentinel.collect();
 
 ## Examples
 
-### Flask — block VPN/proxy signups
+### Flask — route signup decisions
 
 ```python
 from flask import Flask, request, abort, jsonify
 from sentinel import Sentinel, SentinelError
 
 app = Flask(__name__)
-sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
+sentinel = Sentinel()  # reads MASKBREAK_API_KEY from env
 
 @app.route("/signup", methods=["POST"])
 def signup():
     data = request.get_json()
     try:
-        result = sentinel.evaluate(token=data["sentinelToken"])
+        result = sentinel.evaluate(token=data["sentinelToken"],
+                                   fingerprint_event_id=data.get("fingerprintEventId"))
     except SentinelError as e:
         # Fail open OR fail closed — your call. Logged either way.
         app.logger.warning("Sentinel error: %s", e)
@@ -173,6 +190,11 @@ def signup():
     if result and result.is_blocked:
         abort(403, "Signup blocked")
 
+    if result and result.decision == "review":
+        return jsonify({"needs_verification": True}), 202
+
+    # This example explicitly fails open on SDK errors. Choose an endpoint-
+    # specific fallback; do not reuse this policy for transfers or withdrawals.
     # ... your normal signup flow
     return jsonify({"ok": True})
 ```
@@ -181,9 +203,9 @@ def signup():
 
 ```python
 from django.http import JsonResponse
-from sentinel import Sentinel
+from sentinel import Sentinel, SentinelError
 
-sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
+sentinel = Sentinel()  # reads MASKBREAK_API_KEY from env
 
 class FraudCheckMiddleware:
     def __init__(self, get_response):
@@ -192,13 +214,17 @@ class FraudCheckMiddleware:
     def __call__(self, request):
         if request.path.startswith("/api/checkout"):
             token = request.META.get("HTTP_X_SENTINEL_TOKEN")
-            if token:
-                try:
-                    result = sentinel.evaluate(token=token)
-                    if result.is_blocked:
-                        return JsonResponse({"error": "blocked"}, status=403)
-                except Exception:
-                    pass  # fail open
+            if not token:
+                return JsonResponse({"error": "verification required"}, status=400)
+            try:
+                result = sentinel.evaluate(token=token,
+                    fingerprint_event_id=request.META.get("HTTP_X_SENTINEL_FINGERPRINT_EVENT_ID"))
+            except SentinelError:
+                return JsonResponse({"error": "verification unavailable"}, status=503)
+            if result.is_blocked:
+                return JsonResponse({"error": "blocked"}, status=403)
+            if result.decision == "review":
+                return JsonResponse({"error": "additional verification required"}, status=409)
         return self.get_response(request)
 ```
 
@@ -210,7 +236,7 @@ Runnable versions live in [`examples/`](./examples/).
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `api_key` | `$SENTINEL_KEY` (falls back to `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
+| `api_key` | `$MASKBREAK_API_KEY` (falls back to `$SENTINEL_KEY`, then `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
 | `endpoint` | `https://maskbreak.com` | Override base URL (for testing) |
 | `timeout` | `5.0` | Per-request timeout in seconds |
 
@@ -222,31 +248,66 @@ Returns `EvaluateResult`. Raises `SentinelError` on network/API failure.
 - `account_id` — your own user id for this session; enables multi-accounting detection (`device.linked_accounts` / `device.multi_account`).
 - `email` — adds `email.disposable` to the raw response; burner domains escalate `allow` to `review`.
 
+This synchronous SDK forwards only these named inputs. It does not expose a
+timezone input, automatic retries, a circuit breaker, or every REST endpoint.
+Device availability and `degraded` remain accessible through `raw`; missing
+device evidence must not be treated as a clean device result. Account linking
+(`linked_accounts`) is customer-scoped; device `first_seen`/`times_seen` history
+is not customer-scoped.
+
 ### `sentinel.lookup(ip)`
 
 Returns the raw response dict for any public IPv4/IPv6 address (wraps `GET /v1/lookup/{ip}`): `verdict` (`allow`/`review`/`block`), `risk_score` (0–100), `known`, `signals` (`{vpn, proxied, tor, dch, anon}` or `None`), `network` (`{asn, org, country, city}`), `latency_ms`. Shares the per-key hourly quota with `evaluate()`. `known: False` means our feeds hold no data — it is **not** a clean guarantee.
 
+Production bare-IP lookup checks cloud ranges and Tor exits, not live-visit
+VPN/proxy evidence. Legacy `vpn`/`proxied` keys in the shape do not imply those
+checks ran. Use `evaluate()` with browser evidence for VPN/proxy checks. When
+obtaining an IP behind a proxy, trust forwarded headers only from configured
+trusted proxies; never blindly take the first client-supplied value.
+
 ## Testing
 
-Deterministic test tokens exercise your allow / review / block handling end-to-end — no browser needed. Test calls are authenticated and rate-limited like real ones but never billed, stored, or webhooked, and the response carries `test=True`:
+Deterministic `test_*` tokens exercise response handling, not detection quality.
+SDK fixture calls use authentication and quota but do not increment billable
+usage or trigger webhooks; console-originated live-key fixtures can be stored
+as test events. Personal rules and exception pins can change fixture decisions.
 
 ```python
 result = s.evaluate(token="test_vpn")       # also: test_clean, test_proxy, test_datacenter, test_tor
-assert result.decision == "review"
+assert result.decision == "review"          # default policy, no overriding rules/pins
 assert result.test
 ```
 
 No account yet? The public sandbox key accepts the same test tokens:
 
 ```python
-s = Sentinel(api_key="sk_test_sandbox")     # CI/staging — nothing billed, nothing stored
+s = Sentinel(api_key="sk_test_sandbox")     # deterministic fixtures only, no live detection
+```
+
+The public sandbox is separately rate-limited, accepts only supported fixture
+tokens, and does not store events or run live detection. It is not a production
+allowance. A personal `sk_test_...` key runs the live pipeline with real browser
+evidence and your policy; resulting events can be stored with `is_test` set,
+without incrementing usage or firing webhooks. Test keys still have rate limits.
+
+Local checks require no API credentials:
+
+```bash
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
 ```
 
-Every account also has a personal `sk_test_...` key (Settings → API Key) that runs the *complete* live pipeline — real tokens, your rules and exception pins included — while events stay flagged as test and never count toward usage or webhooks.
+The CI matrix targets Python 3.8–3.14 without raising the 3.8 minimum. A configured
+matrix is not a claim that every interpreter was tested locally; inspect its run.
 
 ## Errors
 
-All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+Transport/API failures and unusable success responses raise `SentinelError`.
+The exception carries `.status` (HTTP code) and `.body` (parsed error body) when
+available. Redirects are rejected to avoid forwarding credentials. Configure the
+final API base URL; the client does not retry automatically.
 
 ```python
 from sentinel import Sentinel, SentinelError
@@ -259,13 +320,13 @@ except SentinelError as e:
     elif e.status and 400 <= e.status < 500:
         pass    # bad input, won't recover by retrying
     else:
-        pass    # transient — retry once or fail open
+        pass    # unknown outcome — use the endpoint's explicit fallback policy
 ```
 
 ## Rate limits
 
 Free tier: **1,000 requests/hour** per API key. No monthly cap, no credit
-card. Upgrade at [maskbreak.com](https://maskbreak.com) when you need more.
+card.
 
 ## What Maskbreak detects
 

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/README.md

@@ -1,6 +1,10 @@
 # sentinelsup — Maskbreak Python SDK
 
-Official Python SDK for [Maskbreak](https://maskbreak.com) — a real-time fraud detection API that flags VPNs, residential proxies, antidetect browsers (Kameleo, GoLogin, Multilogin), Tor exit nodes, and AI bots in under 40 ms.
+Official Python SDK for [Maskbreak](https://maskbreak.com). Evaluate SDK-backed
+visits for network and browser risk signals, or look up a public IP for cloud
+range and Tor signals. These are different evidence sources, not interchangeable
+checks. VPN/proxy service names are returned when known; a VPN alone routes to
+review under the default policy, not automatic blocking.
 
 [![PyPI](https://img.shields.io/pypi/v/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
 [![Python versions](https://img.shields.io/pypi/pyversions/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
@@ -8,16 +12,16 @@ Official Python SDK for [Maskbreak](https://maskbreak.com) — a real-time fraud
 
 Zero dependencies — just the standard library. Works with Flask, Django, FastAPI, or bare `urllib`.
 
-## Set up with AI (fastest)
+## Set up with an AI assistant
 
 Using Claude Code, Cursor, Copilot, or any AI coding assistant? Paste this one
 prompt and it wires the whole integration — frontend script, backend check,
 env var, and a test:
 
 > Fetch https://maskbreak.com/integrate.md and follow it to add Maskbreak fraud
-> protection to this app — protect signup, login, and checkout. My API key
-> is sk_live_YOUR_KEY; put it in a SENTINEL_KEY env var, never in
-> client-side code. Then show me how to test it.
+> protection to this app — protect signup, login, and checkout. Read the API key
+> from the server-only MASKBREAK_API_KEY environment variable; I will configure the
+> secret separately. Never put it in client-side code. Show me how to test it.
 
 [`integrate.md`](https://maskbreak.com/integrate.md) is the canonical
 machine-readable integration guide, kept in sync with the live API.
@@ -36,9 +40,12 @@ Python 3.8+. Get a free API key (no credit card) at [maskbreak.com/signup](https
 import os
 from sentinel import Sentinel
 
-s = Sentinel(api_key=os.environ["SENTINEL_KEY"])  # or omit — reads the env var itself
+s = Sentinel(api_key=os.environ["MASKBREAK_API_KEY"])  # or omit — reads the env var itself
 
-result = s.evaluate(token=request.json["sentinelToken"])  # token from the frontend SDK
+result = s.evaluate(
+    token=request.json["sentinelToken"],
+    fingerprint_event_id=request.json.get("fingerprintEventId"),
+)
 
 if result.is_blocked:            # decision == 'block'
     abort(403)
@@ -49,6 +56,14 @@ print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True
 print(result.reasons)         # ['vpn_detected', 'datacenter_asn', ...]
 ```
 
+This is a handler fragment, not a complete signup implementation. Route `review`
+to your verification/review flow; only `allow` is an approval. Keep API keys on
+the server. An unavailable device layer or `raw["degraded"]` is not proof of a
+clean visit; `degraded` describes the network layer only.
+
+Since v0.2.5, `Sentinel()` without a key reads `MASKBREAK_API_KEY`; the older
+`SENTINEL_KEY` and `SENTINEL_API_KEY` names are still read as fallbacks.
+
 Check the signup email against the disposable-domain feed (checked
 transiently, never stored), or look up an arbitrary IP with no browser
 token at all:
@@ -65,7 +80,8 @@ print(info["signals"])              # {'vpn': ..., 'proxied': ..., 'tor': ..., '
 
 ## What you get back
 
-`evaluate()` returns an `EvaluateResult` dataclass:
+`evaluate()` returns an `EvaluateResult` dataclass. The type sketch below uses
+Python 3.10+ annotation syntax for readability; the package minimum stays 3.8:
 
 ```python
 @dataclass
@@ -83,7 +99,7 @@ class EvaluateResult:
     test: bool                  # True for test-token / test-key calls
     raw: dict                   # full upstream response
 
-    is_suspicious: bool         # True if decision != 'allow'
+    is_suspicious: bool         # True for a non-null decision other than 'allow'
     is_blocked: bool            # True if decision == 'block'
 ```
 
@@ -113,7 +129,7 @@ network (VPN/proxy/datacenter) and device (antidetect/bot/tampering):
 
 Forward both fields to your backend with the form submission and pass them to
 `evaluate()` as `token` and `fingerprint_event_id` — without the second one,
-the device-layer signals (antidetect, automation, emulator) never fire. For
+the device-layer signals (antidetect, automation, emulator) are unavailable. For
 fetch/XHR submissions, collect them explicitly:
 
 ```js
@@ -122,20 +138,21 @@ const { token, fingerprintEventId } = await window.Sentinel.collect();
 
 ## Examples
 
-### Flask — block VPN/proxy signups
+### Flask — route signup decisions
 
 ```python
 from flask import Flask, request, abort, jsonify
 from sentinel import Sentinel, SentinelError
 
 app = Flask(__name__)
-sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
+sentinel = Sentinel()  # reads MASKBREAK_API_KEY from env
 
 @app.route("/signup", methods=["POST"])
 def signup():
     data = request.get_json()
     try:
-        result = sentinel.evaluate(token=data["sentinelToken"])
+        result = sentinel.evaluate(token=data["sentinelToken"],
+                                   fingerprint_event_id=data.get("fingerprintEventId"))
     except SentinelError as e:
         # Fail open OR fail closed — your call. Logged either way.
         app.logger.warning("Sentinel error: %s", e)
@@ -144,6 +161,11 @@ def signup():
     if result and result.is_blocked:
         abort(403, "Signup blocked")
 
+    if result and result.decision == "review":
+        return jsonify({"needs_verification": True}), 202
+
+    # This example explicitly fails open on SDK errors. Choose an endpoint-
+    # specific fallback; do not reuse this policy for transfers or withdrawals.
     # ... your normal signup flow
     return jsonify({"ok": True})
 ```
@@ -152,9 +174,9 @@ def signup():
 
 ```python
 from django.http import JsonResponse
-from sentinel import Sentinel
+from sentinel import Sentinel, SentinelError
 
-sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
+sentinel = Sentinel()  # reads MASKBREAK_API_KEY from env
 
 class FraudCheckMiddleware:
     def __init__(self, get_response):
@@ -163,13 +185,17 @@ class FraudCheckMiddleware:
     def __call__(self, request):
         if request.path.startswith("/api/checkout"):
             token = request.META.get("HTTP_X_SENTINEL_TOKEN")
-            if token:
-                try:
-                    result = sentinel.evaluate(token=token)
-                    if result.is_blocked:
-                        return JsonResponse({"error": "blocked"}, status=403)
-                except Exception:
-                    pass  # fail open
+            if not token:
+                return JsonResponse({"error": "verification required"}, status=400)
+            try:
+                result = sentinel.evaluate(token=token,
+                    fingerprint_event_id=request.META.get("HTTP_X_SENTINEL_FINGERPRINT_EVENT_ID"))
+            except SentinelError:
+                return JsonResponse({"error": "verification unavailable"}, status=503)
+            if result.is_blocked:
+                return JsonResponse({"error": "blocked"}, status=403)
+            if result.decision == "review":
+                return JsonResponse({"error": "additional verification required"}, status=409)
         return self.get_response(request)
 ```
 
@@ -181,7 +207,7 @@ Runnable versions live in [`examples/`](./examples/).
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `api_key` | `$SENTINEL_KEY` (falls back to `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
+| `api_key` | `$MASKBREAK_API_KEY` (falls back to `$SENTINEL_KEY`, then `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
 | `endpoint` | `https://maskbreak.com` | Override base URL (for testing) |
 | `timeout` | `5.0` | Per-request timeout in seconds |
 
@@ -193,31 +219,66 @@ Returns `EvaluateResult`. Raises `SentinelError` on network/API failure.
 - `account_id` — your own user id for this session; enables multi-accounting detection (`device.linked_accounts` / `device.multi_account`).
 - `email` — adds `email.disposable` to the raw response; burner domains escalate `allow` to `review`.
 
+This synchronous SDK forwards only these named inputs. It does not expose a
+timezone input, automatic retries, a circuit breaker, or every REST endpoint.
+Device availability and `degraded` remain accessible through `raw`; missing
+device evidence must not be treated as a clean device result. Account linking
+(`linked_accounts`) is customer-scoped; device `first_seen`/`times_seen` history
+is not customer-scoped.
+
 ### `sentinel.lookup(ip)`
 
 Returns the raw response dict for any public IPv4/IPv6 address (wraps `GET /v1/lookup/{ip}`): `verdict` (`allow`/`review`/`block`), `risk_score` (0–100), `known`, `signals` (`{vpn, proxied, tor, dch, anon}` or `None`), `network` (`{asn, org, country, city}`), `latency_ms`. Shares the per-key hourly quota with `evaluate()`. `known: False` means our feeds hold no data — it is **not** a clean guarantee.
 
+Production bare-IP lookup checks cloud ranges and Tor exits, not live-visit
+VPN/proxy evidence. Legacy `vpn`/`proxied` keys in the shape do not imply those
+checks ran. Use `evaluate()` with browser evidence for VPN/proxy checks. When
+obtaining an IP behind a proxy, trust forwarded headers only from configured
+trusted proxies; never blindly take the first client-supplied value.
+
 ## Testing
 
-Deterministic test tokens exercise your allow / review / block handling end-to-end — no browser needed. Test calls are authenticated and rate-limited like real ones but never billed, stored, or webhooked, and the response carries `test=True`:
+Deterministic `test_*` tokens exercise response handling, not detection quality.
+SDK fixture calls use authentication and quota but do not increment billable
+usage or trigger webhooks; console-originated live-key fixtures can be stored
+as test events. Personal rules and exception pins can change fixture decisions.
 
 ```python
 result = s.evaluate(token="test_vpn")       # also: test_clean, test_proxy, test_datacenter, test_tor
-assert result.decision == "review"
+assert result.decision == "review"          # default policy, no overriding rules/pins
 assert result.test
 ```
 
 No account yet? The public sandbox key accepts the same test tokens:
 
 ```python
-s = Sentinel(api_key="sk_test_sandbox")     # CI/staging — nothing billed, nothing stored
+s = Sentinel(api_key="sk_test_sandbox")     # deterministic fixtures only, no live detection
+```
+
+The public sandbox is separately rate-limited, accepts only supported fixture
+tokens, and does not store events or run live detection. It is not a production
+allowance. A personal `sk_test_...` key runs the live pipeline with real browser
+evidence and your policy; resulting events can be stored with `is_test` set,
+without incrementing usage or firing webhooks. Test keys still have rate limits.
+
+Local checks require no API credentials:
+
+```bash
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
 ```
 
-Every account also has a personal `sk_test_...` key (Settings → API Key) that runs the *complete* live pipeline — real tokens, your rules and exception pins included — while events stay flagged as test and never count toward usage or webhooks.
+The CI matrix targets Python 3.8–3.14 without raising the 3.8 minimum. A configured
+matrix is not a claim that every interpreter was tested locally; inspect its run.
 
 ## Errors
 
-All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+Transport/API failures and unusable success responses raise `SentinelError`.
+The exception carries `.status` (HTTP code) and `.body` (parsed error body) when
+available. Redirects are rejected to avoid forwarding credentials. Configure the
+final API base URL; the client does not retry automatically.
 
 ```python
 from sentinel import Sentinel, SentinelError
@@ -230,13 +291,13 @@ except SentinelError as e:
     elif e.status and 400 <= e.status < 500:
         pass    # bad input, won't recover by retrying
     else:
-        pass    # transient — retry once or fail open
+        pass    # unknown outcome — use the endpoint's explicit fallback policy
 ```
 
 ## Rate limits
 
 Free tier: **1,000 requests/hour** per API key. No monthly cap, no credit
-card. Upgrade at [maskbreak.com](https://maskbreak.com) when you need more.
+card.
 
 ## What Maskbreak detects
 

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/examples/django_middleware.py

@@ -4,7 +4,11 @@ Add to settings.py MIDDLEWARE:
     "yourapp.middleware.SentinelMiddleware",
 
 Then ensure your frontend forwards the Sentinel token via the
-X-Sentinel-Token header (set after the SDK injects it on the client).
+X-Sentinel-Token header, and the device event ID via
+X-Sentinel-Fingerprint-Event-Id. Only a live, non-degraded allow decision reaches
+the guarded view; test/sample/sandbox results and review require a separate
+verification flow. This is a middleware example,
+not that verification flow's implementation.
 """
 
 import logging
@@ -20,7 +24,7 @@ _GUARDED_PATHS = ("/api/checkout", "/api/withdraw", "/api/transfer")
 class SentinelMiddleware:
     def __init__(self, get_response):
         self.get_response = get_response
-        self.sentinel = Sentinel()  # reads SENTINEL_API_KEY
+        self.sentinel = Sentinel()  # reads MASKBREAK_API_KEY, older names as fallback
 
     def __call__(self, request):
         if not request.path.startswith(_GUARDED_PATHS):
@@ -31,11 +35,12 @@ class SentinelMiddleware:
             return JsonResponse({"error": "missing X-Sentinel-Token"}, status=400)
 
         try:
-            result = self.sentinel.evaluate(token=token)
+            result = self.sentinel.evaluate(token=token,
+                fingerprint_event_id=request.META.get("HTTP_X_SENTINEL_FINGERPRINT_EVENT_ID"))
         except SentinelError as e:
             log.warning("Sentinel error: %s", e)
-            # Fail open on infra problems; switch to fail-closed for finance flows.
-            return self.get_response(request)
+            # Unknown state must not authorize checkout, withdrawal or transfer.
+            return JsonResponse({"error": "verification unavailable"}, status=503)
 
         if result.is_blocked:
             return JsonResponse(
@@ -43,6 +48,10 @@ class SentinelMiddleware:
                 status=403,
             )
 
+        if (result.decision != "allow" or result.test or
+                any(result.raw.get(flag) for flag in ("test", "sample", "sandbox", "degraded"))):
+            return JsonResponse({"error": "additional verification required"}, status=409)
+
         # Stash on request so the view can read decision/score
         request.sentinel = result
         return self.get_response(request)

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/examples/flask_signup_guard.py

@@ -1,8 +1,8 @@
-"""Flask example — block VPN/proxy signups using Sentinel.
+"""Flask example — route signup risk; a VPN alone means review, not block.
 
 Run:
     pip install flask sentinelsup
-    export SENTINEL_API_KEY=sk_live_...
+    export MASKBREAK_API_KEY=sk_live_...
     python flask_signup_guard.py
 """
 
@@ -12,7 +12,7 @@ from flask import Flask, abort, jsonify, request
 from sentinel import Sentinel, SentinelError
 
 app = Flask(__name__)
-sentinel = Sentinel()  # reads SENTINEL_API_KEY
+sentinel = Sentinel()  # reads MASKBREAK_API_KEY (older SENTINEL_KEY still works)
 
 
 @app.route("/signup", methods=["POST"])
@@ -25,9 +25,11 @@ def signup() -> object:
         abort(400, "missing email or sentinelToken")
 
     try:
-        result = sentinel.evaluate(token=token)
+        result = sentinel.evaluate(token=token,
+                                   fingerprint_event_id=payload.get("fingerprintEventId"),
+                                   email=email)
     except SentinelError as e:
-        # Fail open if Sentinel is down — log and continue.
+        # Explicit fail-open demo policy; do not reuse for sensitive mutations.
         app.logger.warning("Sentinel unavailable: %s", e)
         result = None
 

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/pyproject.toml

@@ -8,8 +8,8 @@ build-backend = "hatchling.build"
 # would install a stranger's code. "sentinelsup" matches the npm scope
 # (@sentinelsup/sdk).
 name = "sentinelsup"
-version = "0.2.3"
-description = "Maskbreak — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response."
+version = "0.2.5"
+description = "Official Maskbreak SDK for browser-backed fraud checks and cloud/Tor IP lookups."
 readme = "README.md"
 requires-python = ">=3.8"
 license = { text = "MIT" }

{sentinelsup-0.2.3 → sentinelsup-0.2.5}/sentinel/__init__.py

@@ -4,7 +4,7 @@ fraud detection API at https://maskbreak.com/v1/evaluate.
 
 Usage:
     from sentinel import Sentinel
-    s = Sentinel()  # reads SENTINEL_KEY or SENTINEL_API_KEY from the env
+    s = Sentinel()  # reads MASKBREAK_API_KEY from the env
     result = s.evaluate(token=request.json["sentinelToken"])
     if result.is_blocked:
         abort(403)
@@ -18,7 +18,14 @@ from urllib import error, parse, request
 
 DEFAULT_ENDPOINT = "https://maskbreak.com"
 DEFAULT_TIMEOUT = 5.0
-__version__ = "0.2.3"
+__version__ = "0.2.5"
+
+
+class _NoRedirect(request.HTTPRedirectHandler):
+    """Do not forward API credentials or replay calls at a redirect target."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
 
 
 class SentinelError(Exception):
@@ -71,13 +78,20 @@ class Sentinel:
         endpoint: str = DEFAULT_ENDPOINT,
         timeout: float = DEFAULT_TIMEOUT,
     ) -> None:
-        # SENTINEL_KEY is the name every doc surface uses; SENTINEL_API_KEY
-        # is kept for existing installs that already adopted it.
-        api_key = api_key or os.environ.get("SENTINEL_KEY") or os.environ.get("SENTINEL_API_KEY")
+        # MASKBREAK_API_KEY is the name every doc surface uses. SENTINEL_KEY
+        # and SENTINEL_API_KEY are older names, still read so existing installs
+        # keep working; the first non-empty one wins.
+        api_key = (
+            api_key
+            or os.environ.get("MASKBREAK_API_KEY")
+            or os.environ.get("SENTINEL_KEY")
+            or os.environ.get("SENTINEL_API_KEY")
+        )
         if not api_key or not isinstance(api_key, str):
             raise SentinelError(
                 "Sentinel: api_key is required. "
-                "Pass it explicitly or set SENTINEL_KEY. "
+                "Pass it explicitly or set MASKBREAK_API_KEY "
+                "(the older SENTINEL_KEY still works). "
                 "Get one free at https://maskbreak.com/signup"
             )
         self.api_key = api_key
@@ -103,9 +117,16 @@ class Sentinel:
         )
 
         try:
-            with request.urlopen(req, timeout=self.timeout) as resp:
-                raw = resp.read().decode("utf-8")
-                return json.loads(raw) if raw else {}
+            with request.build_opener(_NoRedirect()).open(req, timeout=self.timeout) as resp:
+                try:
+                    data = json.loads(resp.read().decode("utf-8"))
+                except (ValueError, UnicodeError):
+                    raise SentinelError("Sentinel: invalid JSON response", status=resp.status) from None
+                if not isinstance(data, dict):
+                    raise SentinelError("Sentinel: expected a JSON object", status=resp.status)
+                return data
+        except SentinelError:
+            raise
         except error.HTTPError as e:
             try:
                 err_body = json.loads(e.read().decode("utf-8"))
@@ -161,6 +182,8 @@ class Sentinel:
             payload["email"] = email
 
         data = self._request("/v1/evaluate", payload)
+        if data.get("decision") not in ("allow", "review", "block"):
+            raise SentinelError("Sentinel: invalid or missing evaluation decision", body=data)
 
         return EvaluateResult(
             decision=data.get("decision"),
@@ -198,7 +221,7 @@ class Sentinel:
         Raises:
             SentinelError: on network failure, timeout, or non-2xx response.
         """
-        if not ip or not isinstance(ip, str):
+        if not isinstance(ip, str) or not ip.strip():
             raise SentinelError(
                 "Sentinel.lookup: ip (public IPv4 or IPv6 address) is required"
             )

sentinelsup-0.2.5/tests/test_client.py

@@ -0,0 +1,165 @@
+"""Standard-library regression tests; all HTTP traffic stays on loopback."""
+
+import json
+import os
+import runpy
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+from unittest.mock import Mock, patch
+
+from sentinel import EvaluateResult, Sentinel, SentinelError
+
+
+class FixtureHandler(BaseHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def do_GET(self):
+        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
+        self.server.calls.append((self.command, self.path, dict(self.headers), body))
+        status, response, headers = self.server.reply
+        if self.path == "/redirect-target":
+            status, response, headers = 200, b'{"decision":"allow"}', {}
+        self.send_response(status)
+        for key, value in headers.items():
+            self.send_header(key, value)
+        self.send_header("Content-Length", str(len(response)))
+        self.end_headers()
+        self.wfile.write(response)
+
+    do_POST = do_GET
+
+
+class ClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), FixtureHandler)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+        cls.thread.join()
+
+    def setUp(self):
+        self.server.calls = []
+        self.server.reply = (200, b'{"decision":"review","future_field":true}', {})
+        self.client = Sentinel("sk_test_fixture", "http://127.0.0.1:%d" % self.server.server_port)
+
+    def test_evaluate_forwards_fields_and_preserves_additive_response(self):
+        result = self.client.evaluate("fixture", "device-event", "account", "a@example.test")
+        method, path, headers, body = self.server.calls[0]
+        self.assertEqual((method, path), ("POST", "/v1/evaluate"))
+        self.assertEqual(headers["Authorization"], "Bearer sk_test_fixture")
+        self.assertEqual(json.loads(body), {"token": "fixture", "fingerprintEventId": "device-event",
+                                            "accountId": "account", "email": "a@example.test"})
+        self.assertEqual(result.decision, "review")
+        self.assertFalse(result.is_blocked)
+        self.assertTrue(result.is_suspicious)
+        self.assertTrue(result.raw["future_field"])
+
+    def test_lookup_trims_and_encodes_ipv6_without_body(self):
+        self.server.reply = (200, b'{"verdict":"allow","known":false}', {})
+        self.assertFalse(self.client.lookup(" 2001:db8::1 ")["known"])
+        method, path, _, body = self.server.calls[0]
+        self.assertEqual((method, path, body), ("GET", "/v1/lookup/2001%3Adb8%3A%3A1", b""))
+
+    def test_blank_lookup_and_missing_token_do_not_send(self):
+        with self.assertRaises(SentinelError):
+            self.client.lookup("  ")
+        with self.assertRaises(SentinelError):
+            self.client.evaluate("")
+        self.assertEqual(self.server.calls, [])
+
+    def test_invalid_success_bodies_raise_sdk_error(self):
+        for body in (b"", b"<html>gateway</html>", b"null", b"[]", b'"text"', b"42"):
+            with self.subTest(body=body):
+                self.server.reply = (200, body, {})
+                with self.assertRaises(SentinelError) as caught:
+                    self.client.evaluate("fixture")
+                self.assertEqual(caught.exception.status, 200)
+
+    def test_missing_or_invalid_decisions_are_not_success(self):
+        for data in ({}, {"decision": None}, {"decision": "unexpected"}, {"decision": []}):
+            with self.subTest(data=data):
+                self.server.reply = (200, json.dumps(data).encode(), {})
+                with self.assertRaisesRegex(SentinelError, "evaluation decision"):
+                    self.client.evaluate("fixture")
+
+    def test_api_errors_preserve_status_and_object_body(self):
+        self.server.reply = (429, b'{"error":"Try later"}', {})
+        with self.assertRaises(SentinelError) as caught:
+            self.client.evaluate("fixture")
+        self.assertEqual(caught.exception.status, 429)
+        self.assertEqual(caught.exception.body, {"error": "Try later"})
+
+    def test_redirect_does_not_forward_key_or_replay_request(self):
+        target = "http://localhost:%d/redirect-target" % self.server.server_port
+        self.server.reply = (302, b'{}', {"Location": target})
+        with self.assertRaises(SentinelError) as caught:
+            self.client.lookup("203.0.113.1")
+        self.assertEqual(caught.exception.status, 302)
+        self.assertEqual(len(self.server.calls), 1, "redirect target must not receive the API key")
+
+    def test_environment_key_precedence(self):
+        env = {"MASKBREAK_API_KEY": "current", "SENTINEL_KEY": "primary", "SENTINEL_API_KEY": "legacy"}
+        with patch.dict(os.environ, env):
+            self.assertEqual(Sentinel().api_key, "current")
+            self.assertEqual(Sentinel("explicit").api_key, "explicit")
+            os.environ.pop("MASKBREAK_API_KEY")
+            self.assertEqual(Sentinel().api_key, "primary")
+            os.environ.pop("SENTINEL_KEY")
+            self.assertEqual(Sentinel().api_key, "legacy")
+
+    def test_environment_key_new_name_alone(self):
+        with patch.dict(os.environ, {"MASKBREAK_API_KEY": "current"}):
+            for old in ("SENTINEL_KEY", "SENTINEL_API_KEY"):
+                os.environ.pop(old, None)
+            self.assertEqual(Sentinel().api_key, "current")
+
+    def test_missing_key_names_the_current_variable(self):
+        with patch.dict(os.environ, {}):
+            for name in ("MASKBREAK_API_KEY", "SENTINEL_KEY", "SENTINEL_API_KEY"):
+                os.environ.pop(name, None)
+            with self.assertRaises(SentinelError) as caught:
+                Sentinel()
+            self.assertIn("MASKBREAK_API_KEY", str(caught.exception))
+
+    def test_result_helpers_keep_review_distinct_from_block(self):
+        for decision in ("allow", "review", "block"):
+            result = EvaluateResult(decision=decision)
+            self.assertEqual(result.is_blocked, decision == "block")
+            self.assertEqual(result.is_suspicious, decision != "allow")
+
+
+class DjangoGuardTests(unittest.TestCase):
+    def test_financial_guard_requires_live_complete_allow_before_view(self):
+        http = ModuleType("django.http")
+        http.JsonResponse = lambda body, status: SimpleNamespace(status_code=status)
+        with patch.dict(sys.modules, {"django": ModuleType("django"), "django.http": http}):
+            example = runpy.run_path(str(Path(__file__).resolve().parents[1] / "examples" / "django_middleware.py"))
+        for decision, flag, status in [("allow", None, 200), ("review", None, 409), ("block", None, 403)] + [
+            ("allow", flag, 409) for flag in ("test", "sample", "sandbox", "degraded")
+        ]:
+            with self.subTest(decision=decision, flag=flag):
+                view = Mock(return_value=SimpleNamespace(status_code=200))
+                with patch.dict(os.environ, {"MASKBREAK_API_KEY": "sk_test_fixture"}):
+                    middleware = example["SentinelMiddleware"](view)
+                middleware.sentinel = Mock()
+                middleware.sentinel.evaluate.return_value = EvaluateResult(
+                    decision=decision, test=flag == "test", raw={flag: True} if flag else {})
+                request = SimpleNamespace(path="/api/transfer", META={
+                    "HTTP_X_SENTINEL_TOKEN": "fixture", "HTTP_X_SENTINEL_FINGERPRINT_EVENT_ID": "device-event"})
+                self.assertEqual(middleware(request).status_code, status)
+                self.assertEqual(view.call_count, 1 if status == 200 else 0)
+                middleware.sentinel.evaluate.assert_called_once_with(token="fixture", fingerprint_event_id="device-event")
+
+
+if __name__ == "__main__":
+    unittest.main()