feat: direct validateLicense endpoint. no heartbeat started.

Author: RAZKOM

AGENTS.md

@@ -9,7 +9,7 @@ AuthForge is a license key validation service. Your app sends a license key + ha
 
 ## Billing model (so you can pick sensible intervals)
 
-- **1 `login()` = 1 credit** (one `/auth/validate` debit).
+- **1 `login()` or `validate_license()` = 1 credit** (one `/auth/validate` debit each).
 - **10 heartbeats = 1 credit** (billed on every 10th successful heartbeat per license).
 - Any `heartbeat_interval` is safe — from `1` (server apps) to `900` (15 min, desktop apps). Revocations always take effect on the **next** heartbeat regardless of interval.
 
@@ -63,7 +63,7 @@ if __name__ == "__main__":
 | `heartbeat_mode` | `str` | yes | — | `"SERVER"` or `"LOCAL"` (case-insensitive) |
 | `heartbeat_interval` | `int` | no | `900` | Seconds between heartbeats (any value ≥ 1) |
 | `api_base_url` | `str` | no | `https://auth.authforge.cc` | API base URL |
-| `on_failure` | `Callable[[str, Optional[Exception]], None] \| None` | no | `None` | Called on login/heartbeat/network failure; if omitted, process exits via `os._exit(1)` |
+| `on_failure` | `Callable[[str, Optional[Exception]], None] \| None` | no | `None` | Called on login/heartbeat/network failure; if omitted, process exits via `os._exit(1)` (not used by `validate_license`) |
 | `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. |
@@ -75,6 +75,7 @@ For Telegram/Discord bot flows, prefer immutable IDs (`tg:<user_id>`, `discord:<
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `login(license_key: str)` | `bool` | Validates license, verifies signatures, starts heartbeat thread |
+| `validate_license(license_key: str)` | `ValidateLicenseResult` | Same validate + signatures as login; no session persistence or heartbeat; **never** calls `on_failure` or `os._exit` |
 | `logout()` | `None` | Stops heartbeat and clears session state |
 | `is_authenticated()` | `bool` | Whether a session token is present and marked authenticated |
 | `get_session_data()` | `dict \| None` | Decoded signed payload map |

README.md

@@ -67,7 +67,7 @@ client = AuthForgeClient(
 
 ## Billing
 
-- **1 `login()` call = 1 credit** (one `/auth/validate` debit).
+- **1 `login()` or `validate_license()` call = 1 credit** (one `/auth/validate` debit each).
 - **10 heartbeats on the same license = 1 credit** (billed every 10th successful heartbeat).
 
 A desktop app running 6h/day at a 15-minute interval burns ~3–4 credits/day. A server app running 24/7 at a 1-minute interval burns ~145 credits/day — pick the interval based on how fast you need revocations to propagate (they always land on the **next** heartbeat).
@@ -77,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`) |
+| `validate_license(license_key)` | `ValidateLicenseResult` | Same `/auth/validate` + signatures as `login`; does not store session or start heartbeats; returns a dict with `valid` / `code` and **never** calls `on_failure` or `os._exit` |
 | `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 |
@@ -94,6 +95,8 @@ 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.
 
+**`validate_license()`** does not trigger `on_failure` or `os._exit` — check `result["valid"]` and `result["code"]`.
+
 Recognized server errors:
 `invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`
 

authforge.py

@@ -11,14 +11,33 @@
 import urllib.error
 import urllib.request
 import uuid
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Literal, Optional, TypedDict, Union
 from cryptography.exceptions import InvalidSignature
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 
 
 DEFAULT_API_BASE_URL = "https://auth.authforge.cc"
 RATE_LIMIT_RETRY_DELAYS = (2, 5)
 NETWORK_RETRY_DELAY = 2
+class ValidateLicenseSuccess(TypedDict):
+    valid: Literal[True]
+    session_token: str
+    expires_in: int
+    session_data: Dict[str, Any]
+    app_variables: Optional[Dict[str, Any]]
+    license_variables: Optional[Dict[str, Any]]
+    key_id: Optional[str]
+
+
+class ValidateLicenseFailure(TypedDict):
+    valid: Literal[False]
+    code: str
+    error: str
+
+
+ValidateLicenseResult = Union[ValidateLicenseSuccess, ValidateLicenseFailure]
+
+
 KNOWN_SERVER_ERRORS = {
     "invalid_app",
     "invalid_key",
@@ -109,6 +128,36 @@ def login(self, license_key: str) -> bool:
             self._fail("login_failed", exc)
             return False
 
+    def validate_license(self, license_key: str) -> ValidateLicenseResult:
+        """Validate like :meth:`login` (same /auth/validate + signatures) without storing
+        session state or starting the heartbeat thread."""
+        if not license_key or not isinstance(license_key, str):
+            raise ValueError("license_key must be a non-empty string")
+        try:
+            body: Dict[str, Any] = {
+                "appId": self.app_id,
+                "appSecret": self.app_secret,
+                "licenseKey": license_key,
+                "hwid": self._hwid,
+                "nonce": self._generate_nonce(),
+            }
+            if self.ttl_seconds is not None:
+                body["ttlSeconds"] = self.ttl_seconds
+            response_obj = self._post_json("/auth/validate", body, skip_failure_hook=True)
+            expected_nonce = str(body.get("nonce", "")).strip()
+            parsed = self._parse_validate_success(response_obj, expected_nonce)
+            return {
+                "valid": True,
+                "session_token": parsed["session_token"],
+                "expires_in": parsed["expires_in"],
+                "session_data": parsed["session_data"],
+                "app_variables": parsed["app_variables"],
+                "license_variables": parsed["license_variables"],
+                "key_id": parsed["key_id"],
+            }
+        except Exception as exc:
+            return {"valid": False, "code": str(exc), "error": str(exc)}
+
     def self_ban(
         self,
         *,
@@ -250,13 +299,9 @@ def _validate_and_store(self, license_key: str) -> None:
             context="validate",
         )
 
-    def _apply_signed_response(
-        self,
-        response_obj: Dict[str, Any],
-        expected_nonce: str,
-        license_key: Optional[str],
-        context: str,
-    ) -> None:
+    def _parse_validate_success(
+        self, response_obj: Dict[str, Any], expected_nonce: str
+    ) -> Dict[str, Any]:
         status = response_obj.get("status")
         if not self._is_success_status(status):
             error_code = self._extract_server_error(response_obj)
@@ -288,21 +333,46 @@ def _apply_signed_response(
         if expires_in is None:
             raise ValueError("missing_expiresIn")
 
+        return {
+            "session_token": session_token,
+            "expires_in": int(expires_in),
+            "session_data": dict(payload_json),
+            "app_variables": self._extract_optional_map(payload_json.get("appVariables")),
+            "license_variables": self._extract_optional_map(
+                payload_json.get("licenseVariables")
+            ),
+            "key_id": key_id if isinstance(key_id, str) else None,
+            "raw_payload_b64": raw_payload_b64,
+            "signature": signature,
+        }
+
+    def _apply_signed_response(
+        self,
+        response_obj: Dict[str, Any],
+        expected_nonce: str,
+        license_key: Optional[str],
+        context: str,
+    ) -> None:
+        parsed = self._parse_validate_success(response_obj, expected_nonce)
+        _ = context
+
         with self._lock:
             if license_key is not None:
                 self._license_key = license_key
-            self._session_token = session_token
-            self._session_expires_in = int(expires_in)
+            self._session_token = parsed["session_token"]
+            self._session_expires_in = int(parsed["expires_in"])
             self._last_nonce = expected_nonce
-            self._raw_payload_b64 = raw_payload_b64
-            self._signature = signature
-            self._key_id = key_id
-            self._session_data = dict(payload_json)
-            self._app_variables = self._extract_optional_map(payload_json.get("appVariables"))
-            self._license_variables = self._extract_optional_map(payload_json.get("licenseVariables"))
+            self._raw_payload_b64 = parsed["raw_payload_b64"]
+            self._signature = parsed["signature"]
+            self._key_id = parsed["key_id"]
+            self._session_data = dict(parsed["session_data"])
+            self._app_variables = parsed["app_variables"]
+            self._license_variables = parsed["license_variables"]
             self._authenticated = True
 
-    def _post_json(self, path: str, data: Dict[str, Any]) -> Dict[str, Any]:
+    def _post_json(
+        self, path: str, data: Dict[str, Any], *, skip_failure_hook: bool = False
+    ) -> Dict[str, Any]:
         url = f"{self.api_base_url}{path}"
         body = dict(data)
         rate_attempt = 0
@@ -342,7 +412,8 @@ def _post_json(self, path: str, data: Dict[str, Any]) -> Dict[str, Any]:
                         network_attempt += 1
                         time.sleep(NETWORK_RETRY_DELAY)
                         continue
-                    self._fail("network_error", exc)
+                    if not skip_failure_hook:
+                        self._fail("network_error", exc)
                     raise RuntimeError(f"url_error: {exc}") from exc
 
             is_rate_limited = (

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "authforge-sdk"
-version = "1.0.2"
+version = "1.0.3"
 description = "Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses."
 readme = "README.md"
 requires-python = ">=3.9"

test_authforge.py

@@ -51,6 +51,76 @@ def test_invalid_vectors_fail(self) -> None:
                 self.assertEqual(ctx.exception.args[0], "signature_mismatch")
 
 
+class ValidateLicenseTests(unittest.TestCase):
+    def test_validate_license_success_no_heartbeat(self) -> None:
+        vectors = _load_test_vectors()
+        success_case = next(
+            case for case in vectors["cases"] if case["id"] == "validate_success"
+        )
+        nonce = "nonce-validate-001"
+        mock_resp = MagicMock()
+        mock_resp.status = 200
+        mock_resp.read.return_value = json.dumps(
+            {
+                "status": "ok",
+                "payload": success_case["payload"],
+                "signature": success_case["signature"],
+                "keyId": "signing-key-1",
+            },
+            separators=(",", ":"),
+        ).encode("utf-8")
+
+        urlopen_cm = MagicMock()
+        urlopen_cm.__enter__.return_value = mock_resp
+        urlopen_cm.__exit__.return_value = None
+
+        with (
+            patch("authforge.urllib.request.urlopen", return_value=urlopen_cm),
+            patch.object(AuthForgeClient, "_generate_nonce", return_value=nonce),
+        ):
+            client = AuthForgeClient(
+                "app-id",
+                "app-secret",
+                vectors["publicKey"],
+                "LOCAL",
+                heartbeat_interval=86400,
+            )
+            result = client.validate_license("license-key")
+
+        self.assertTrue(result["valid"])
+        self.assertFalse(client._heartbeat_started)
+        self.assertFalse(client.is_authenticated())
+        self.assertEqual(result["session_token"], "session.validate.token")
+        self.assertEqual(result["app_variables"], {"tier": "pro"})
+
+    def test_validate_license_failure_no_heartbeat(self) -> None:
+        vectors = _load_test_vectors()
+        mock_resp = MagicMock()
+        mock_resp.status = 200
+        mock_resp.read.return_value = json.dumps(
+            {"status": "invalid_key", "error": "invalid_key"},
+            separators=(",", ":"),
+        ).encode("utf-8")
+
+        urlopen_cm = MagicMock()
+        urlopen_cm.__enter__.return_value = mock_resp
+        urlopen_cm.__exit__.return_value = None
+
+        with patch("authforge.urllib.request.urlopen", return_value=urlopen_cm):
+            client = AuthForgeClient(
+                "app-id",
+                "app-secret",
+                vectors["publicKey"],
+                "LOCAL",
+                heartbeat_interval=86400,
+            )
+            result = client.validate_license("bad")
+
+        self.assertFalse(result["valid"])
+        self.assertEqual(result["code"], "invalid_key")
+        self.assertFalse(client._heartbeat_started)
+
+
 class LoginFlowTests(unittest.TestCase):
     def test_login_parses_and_stores_signed_payload(self) -> None:
         vectors = _load_test_vectors()