feat: self-ban support, HWID override support, release 1.0.2

Author: RAZKOM

AGENTS.md

@@ -66,6 +66,9 @@ if __name__ == "__main__":
 | `on_failure` | `Callable[[str, Optional[Exception]], None] \| None` | no | `None` | Called on login/heartbeat/network failure; if omitted, process exits via `os._exit(1)` |
 | `request_timeout` | `int` | no | `15` | HTTP timeout (seconds) |
 | `ttl_seconds` | `int \| None` | no | `None` (server default: 86400) | Requested session token lifetime. Server clamps to `[3600, 604800]`; preserved across heartbeat refreshes. |
+| `hwid_override` | `str \| None` | no | `None` | Optional custom HWID/subject string. When set to a non-empty value (for example `tg:123456789`), the SDK sends it instead of generating a machine fingerprint. |
+
+For Telegram/Discord bot flows, prefer immutable IDs (`tg:<user_id>`, `discord:<user_id>`) instead of usernames.
 
 ## Methods
 

README.md

@@ -51,6 +51,19 @@ else:
 | `on_failure` | callable | `None` | Callback `(reason: str, exc: Exception | None)` on auth failure |
 | `request_timeout` | int | `15` | HTTP request timeout in seconds |
 | `ttl_seconds` | `int \| None` | `None` (server default: 86400) | Requested session token lifetime. Server clamps to `[3600, 604800]`; preserved across heartbeat refreshes. |
+| `hwid_override` | `str \| None` | `None` | Optional custom hardware/subject identifier. When set to a non-empty value, the SDK uses it instead of machine fingerprinting. |
+
+### Identity-based binding example (Telegram/Discord)
+
+```python
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",
+    public_key="YOUR_PUBLIC_KEY",
+    heartbeat_mode="SERVER",
+    hwid_override=f"tg:{telegram_user_id}",  # or f"discord:{discord_user_id}"
+)
+```
 
 ## Billing
 
@@ -64,6 +77,7 @@ A desktop app running 6h/day at a 15-minute interval burns ~3–4 credits/day. A
 | Method | Returns | Description |
 |---|---|---|
 | `login(license_key)` | `bool` | Validates key and stores signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
+| `self_ban(...)` | `dict` | Requests `/auth/selfban` to blacklist HWID/IP and optionally revoke (session-authenticated only) |
 | `logout()` | `None` | Stops heartbeat and clears all session/auth state |
 | `is_authenticated()` | `bool` | True when an active authenticated session exists |
 | `get_session_data()` | `dict \| None` | Full decoded payload map |
@@ -81,7 +95,7 @@ A desktop app running 6h/day at a 15-minute interval burns ~3–4 credits/day. A
 If authentication fails (login rejected, heartbeat fails, signature mismatch, etc.), the SDK calls your `on_failure` callback if one is provided. If no callback is set, **the SDK calls `os._exit(1)` to terminate the process.** This is intentional — it prevents your app from running without a valid license.
 
 Recognized server errors:
-`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `bad_request`
+`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`
 
 Request retries are automatic inside the internal HTTP layer:
 - `rate_limited`: retry after 2s, then 5s (max 3 attempts total)
@@ -105,9 +119,33 @@ client = AuthForgeClient(
 )
 ```
 
+## Self-ban (tamper response)
+
+Use `self_ban()` when anti-tamper checks trigger:
+
+```python
+# Post-session (authenticated): defaults to revoke + HWID/IP blacklist.
+client.self_ban()
+
+# Pre-session: pass license_key, SDK automatically disables revoke_license.
+client.self_ban(license_key="AF-XXXX-XXXX-XXXX")
+
+# Custom flags:
+client.self_ban(
+    blacklist_hwid=True,
+    blacklist_ip=True,
+    revoke_license=False,
+)
+```
+
+`self_ban()` automatically chooses mode:
+- Uses post-session mode when a session token is available (`session_token` arg or current SDK session).
+- Falls back to pre-session mode using `license_key` + nonce + app secret.
+- In pre-session mode, revoke is forced off client-side to avoid unsafe key revocations.
+
 ## How It Works
 
-1. **Login** — Collects a hardware fingerprint (MAC, CPU, disk serial), generates a random nonce, and sends everything to the AuthForge API. The server validates the license key, binds the HWID, deducts a credit, and returns a signed payload. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
+1. **Login** — Uses `hwid_override` if provided; otherwise collects a hardware fingerprint (MAC, CPU, disk serial). It then generates a random nonce and sends everything to the AuthForge API. The server validates the license key, binds the HWID, deducts a credit, and returns a signed payload. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
 
 2. **Heartbeat** — A background daemon thread checks in at the configured interval. In SERVER mode, it sends a fresh nonce and verifies the response. In LOCAL mode, it re-verifies the stored signature and checks expiry without network calls.
 
@@ -122,6 +160,8 @@ The SDK generates a deterministic hardware fingerprint by hashing:
 
 Each component falls back gracefully if it can't be read (e.g. permissions issues). The HWID is sent with every auth request so the server can enforce per-device license limits.
 
+For non-device identities (for example Telegram users), pass `hwid_override` such as `tg:<user_id>`.
+
 ## Test Vectors
 
 The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior.

authforge.py

@@ -32,6 +32,7 @@
     "replay_detected",
     "app_disabled",
     "session_expired",
+    "revoke_requires_session",
     "bad_request",
     "system_error",
 }
@@ -49,6 +50,7 @@ def __init__(
         on_failure: Optional[Callable[[str, Optional[Exception]], None]] = None,
         request_timeout: int = 15,
         ttl_seconds: Optional[int] = None,
+        hwid_override: Optional[str] = None,
     ) -> None:
         if not app_id or not isinstance(app_id, str):
             raise ValueError("app_id must be a non-empty string")
@@ -92,7 +94,7 @@ def __init__(
         self._app_variables: Optional[Dict[str, Any]] = None
         self._license_variables: Optional[Dict[str, Any]] = None
         self._authenticated = False
-        self._hwid = self._get_hwid()
+        self._hwid = self._resolve_hwid(hwid_override)
         self._ed25519_public_key = self._load_public_key(public_key)
 
     def login(self, license_key: str) -> bool:
@@ -107,6 +109,65 @@ def login(self, license_key: str) -> bool:
             self._fail("login_failed", exc)
             return False
 
+    def self_ban(
+        self,
+        *,
+        license_key: Optional[str] = None,
+        session_token: Optional[str] = None,
+        revoke_license: bool = True,
+        blacklist_hwid: bool = True,
+        blacklist_ip: bool = True,
+    ) -> Dict[str, Any]:
+        resolved_session = (
+            session_token.strip()
+            if isinstance(session_token, str) and session_token.strip()
+            else None
+        )
+        with self._lock:
+            current_session = self._session_token
+            current_license = self._license_key
+            hwid = self._hwid
+        resolved_session = resolved_session or current_session
+
+        if resolved_session:
+            body: Dict[str, Any] = {
+                "appId": self.app_id,
+                "sessionToken": resolved_session,
+                "hwid": hwid,
+                "revokeLicense": bool(revoke_license),
+                "blacklistHwid": bool(blacklist_hwid),
+                "blacklistIp": bool(blacklist_ip),
+            }
+            response_obj = self._post_json("/auth/selfban", body)
+            if not self._is_success_status(response_obj.get("status")):
+                raise ValueError(self._extract_server_error(response_obj))
+            return response_obj
+
+        resolved_license = (
+            license_key.strip()
+            if isinstance(license_key, str) and license_key.strip()
+            else None
+        )
+        resolved_license = resolved_license or current_license
+        if not resolved_license:
+            raise ValueError("missing_license_key")
+
+        body = {
+            "appId": self.app_id,
+            "appSecret": self.app_secret,
+            "licenseKey": resolved_license,
+            "hwid": hwid,
+            "nonce": self._generate_nonce(),
+            # Pre-session self-ban cannot revoke licenses.
+            "revokeLicense": False,
+            "blacklistHwid": bool(blacklist_hwid),
+            "blacklistIp": bool(blacklist_ip),
+        }
+        response_obj = self._post_json("/auth/selfban", body)
+        if not self._is_success_status(response_obj.get("status")):
+            raise ValueError(self._extract_server_error(response_obj))
+        return response_obj
+
     def _start_heartbeat_once(self) -> None:
         with self._lock:
             if self._heartbeat_started:
@@ -310,6 +371,13 @@ def _get_hwid(self) -> str:
         material = f"mac:{mac}|cpu:{cpu}|disk:{disk}"
         return hashlib.sha256(material.encode("utf-8")).hexdigest()
 
+    def _resolve_hwid(self, hwid_override: Optional[str]) -> str:
+        if isinstance(hwid_override, str):
+            trimmed = hwid_override.strip()
+            if trimmed:
+                return trimmed
+        return self._get_hwid()
+
     def _safe_mac_address(self) -> str:
         try:
             return f"{uuid.getnode():012x}"