authforge-sdk 1.0.0__tar.gz

authforge_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuthForge
+
+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.

authforge_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: authforge-sdk
+Version: 1.0.0
+Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
+Author: AuthForge
+License: MIT
+Project-URL: Homepage, https://authforge.cc
+Project-URL: Documentation, https://docs.authforge.cc
+Project-URL: Source, https://github.com/AuthForgeCC/authforge-python
+Project-URL: Issues, https://github.com/AuthForgeCC/authforge-python/issues
+Keywords: authforge,license,licensing,hwid,authentication
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0.0
+Dynamic: license-file
+
+# AuthForge Python SDK
+
+Official Python SDK for [AuthForge](https://authforge.cc) — credit-based license key authentication with Ed25519-verified responses.
+
+Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
+
+## Installation
+
+The distribution on [PyPI](https://pypi.org/project/authforge-sdk/) is **`authforge-sdk`** (same idea as scoped npm names: install name ≠ import path). After installing, import the **`authforge`** module:
+
+```bash
+pip install authforge-sdk
+```
+
+**Alternative:** copy `authforge.py` into your project if you need a single-file vendored layout (you must still satisfy the `cryptography` dependency yourself).
+
+## Quick Start
+
+After **`pip install authforge-sdk`** (or vendoring `authforge.py`), use:
+
+```python
+from authforge import AuthForgeClient
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",           # from your AuthForge dashboard
+    app_secret="YOUR_APP_SECRET",   # from your AuthForge dashboard
+    public_key="YOUR_PUBLIC_KEY",   # from your AuthForge dashboard
+    heartbeat_mode="SERVER",        # "SERVER" or "LOCAL"
+)
+
+license_key = input("Enter license key: ")
+
+if client.login(license_key):
+    print("Authenticated!")
+    # Your app logic here — heartbeats run automatically in the background
+else:
+    print("Invalid license key.")
+    exit(1)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app_id` | str | required | Your application ID from the AuthForge dashboard |
+| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `public_key` | str | required | App Ed25519 public key (base64) from dashboard |
+| `heartbeat_mode` | str | required | `"SERVER"` or `"LOCAL"` (see below) |
+| `heartbeat_interval` | int | `900` | Seconds between heartbeat checks (any value ≥ 1; default 15 min) |
+| `api_base_url` | str | `https://auth.authforge.cc` | API endpoint |
+| `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. |
+
+## Billing
+
+- **1 `login()` call = 1 credit** (one `/auth/validate` debit).
+- **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).
+
+## Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `login(license_key)` | `bool` | Validates key and stores signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
+| `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 |
+| `get_app_variables()` | `dict \| None` | App-scoped variables map |
+| `get_license_variables()` | `dict \| None` | License-scoped variables map |
+
+## Heartbeat Modes
+
+**SERVER** — The SDK calls `/auth/heartbeat` every `heartbeat_interval` seconds with a fresh nonce, verifies signature + nonce, and triggers failure on invalid session state.
+
+**LOCAL** — No network calls. The SDK re-verifies stored signature state and checks expiry timestamp locally. If expired, it triggers failure with `session_expired`.
+
+## Failure Handling
+
+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`
+
+Request retries are automatic inside the internal HTTP layer:
+- `rate_limited`: retry after 2s, then 5s (max 3 attempts total)
+- network failure: retry once after 2s
+- every retry regenerates a fresh nonce
+
+```python
+def handle_auth_failure(reason, exception):
+    print(f"Auth failed: {reason}")
+    if exception:
+        print(f"Details: {exception}")
+    # Clean up and exit gracefully
+    sys.exit(1)
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",
+    public_key="YOUR_PUBLIC_KEY",
+    heartbeat_mode="SERVER",
+    on_failure=handle_auth_failure,
+)
+```
+
+## 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.
+
+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.
+
+3. **Crypto** — Both `/validate` and `/heartbeat` responses are signed by AuthForge with your app's Ed25519 private key. The SDK verifies every signed `payload` using your configured `public_key` and rejects tampered responses.
+
+## Hardware ID
+
+The SDK generates a deterministic hardware fingerprint by hashing:
+- MAC address
+- CPU identifier
+- Disk serial number
+
+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.
+
+## Test Vectors
+
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior.
+
+## Requirements
+
+- Python 3.9+
+- Dependency: `cryptography`
+
+## License
+
+MIT

authforge_sdk-1.0.0/README.md

@@ -0,0 +1,136 @@
+# AuthForge Python SDK
+
+Official Python SDK for [AuthForge](https://authforge.cc) — credit-based license key authentication with Ed25519-verified responses.
+
+Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
+
+## Installation
+
+The distribution on [PyPI](https://pypi.org/project/authforge-sdk/) is **`authforge-sdk`** (same idea as scoped npm names: install name ≠ import path). After installing, import the **`authforge`** module:
+
+```bash
+pip install authforge-sdk
+```
+
+**Alternative:** copy `authforge.py` into your project if you need a single-file vendored layout (you must still satisfy the `cryptography` dependency yourself).
+
+## Quick Start
+
+After **`pip install authforge-sdk`** (or vendoring `authforge.py`), use:
+
+```python
+from authforge import AuthForgeClient
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",           # from your AuthForge dashboard
+    app_secret="YOUR_APP_SECRET",   # from your AuthForge dashboard
+    public_key="YOUR_PUBLIC_KEY",   # from your AuthForge dashboard
+    heartbeat_mode="SERVER",        # "SERVER" or "LOCAL"
+)
+
+license_key = input("Enter license key: ")
+
+if client.login(license_key):
+    print("Authenticated!")
+    # Your app logic here — heartbeats run automatically in the background
+else:
+    print("Invalid license key.")
+    exit(1)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app_id` | str | required | Your application ID from the AuthForge dashboard |
+| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `public_key` | str | required | App Ed25519 public key (base64) from dashboard |
+| `heartbeat_mode` | str | required | `"SERVER"` or `"LOCAL"` (see below) |
+| `heartbeat_interval` | int | `900` | Seconds between heartbeat checks (any value ≥ 1; default 15 min) |
+| `api_base_url` | str | `https://auth.authforge.cc` | API endpoint |
+| `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. |
+
+## Billing
+
+- **1 `login()` call = 1 credit** (one `/auth/validate` debit).
+- **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).
+
+## Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `login(license_key)` | `bool` | Validates key and stores signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
+| `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 |
+| `get_app_variables()` | `dict \| None` | App-scoped variables map |
+| `get_license_variables()` | `dict \| None` | License-scoped variables map |
+
+## Heartbeat Modes
+
+**SERVER** — The SDK calls `/auth/heartbeat` every `heartbeat_interval` seconds with a fresh nonce, verifies signature + nonce, and triggers failure on invalid session state.
+
+**LOCAL** — No network calls. The SDK re-verifies stored signature state and checks expiry timestamp locally. If expired, it triggers failure with `session_expired`.
+
+## Failure Handling
+
+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`
+
+Request retries are automatic inside the internal HTTP layer:
+- `rate_limited`: retry after 2s, then 5s (max 3 attempts total)
+- network failure: retry once after 2s
+- every retry regenerates a fresh nonce
+
+```python
+def handle_auth_failure(reason, exception):
+    print(f"Auth failed: {reason}")
+    if exception:
+        print(f"Details: {exception}")
+    # Clean up and exit gracefully
+    sys.exit(1)
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",
+    public_key="YOUR_PUBLIC_KEY",
+    heartbeat_mode="SERVER",
+    on_failure=handle_auth_failure,
+)
+```
+
+## 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.
+
+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.
+
+3. **Crypto** — Both `/validate` and `/heartbeat` responses are signed by AuthForge with your app's Ed25519 private key. The SDK verifies every signed `payload` using your configured `public_key` and rejects tampered responses.
+
+## Hardware ID
+
+The SDK generates a deterministic hardware fingerprint by hashing:
+- MAC address
+- CPU identifier
+- Disk serial number
+
+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.
+
+## Test Vectors
+
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior.
+
+## Requirements
+
+- Python 3.9+
+- Dependency: `cryptography`
+
+## License
+
+MIT

authforge_sdk-1.0.0/authforge.py

@@ -0,0 +1,500 @@
+import base64
+import hashlib
+import json
+import os
+import platform
+import secrets
+import subprocess
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Optional
+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
+KNOWN_SERVER_ERRORS = {
+    "invalid_app",
+    "invalid_key",
+    "expired",
+    "revoked",
+    "hwid_mismatch",
+    "no_credits",
+    "app_burn_cap_reached",
+    "blocked",
+    "rate_limited",
+    "replay_detected",
+    "app_disabled",
+    "session_expired",
+    "bad_request",
+    "system_error",
+}
+
+
+class AuthForgeClient:
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        public_key: str,
+        heartbeat_mode: str,
+        heartbeat_interval: int = 900,
+        api_base_url: str = DEFAULT_API_BASE_URL,
+        on_failure: Optional[Callable[[str, Optional[Exception]], None]] = None,
+        request_timeout: int = 15,
+        ttl_seconds: Optional[int] = None,
+    ) -> None:
+        if not app_id or not isinstance(app_id, str):
+            raise ValueError("app_id must be a non-empty string")
+        if not app_secret or not isinstance(app_secret, str):
+            raise ValueError("app_secret must be a non-empty string")
+        if not public_key or not isinstance(public_key, str):
+            raise ValueError("public_key must be a non-empty base64 string")
+        mode = (heartbeat_mode or "").upper()
+        if mode not in {"LOCAL", "SERVER"}:
+            raise ValueError("heartbeat_mode must be LOCAL or SERVER")
+        if heartbeat_interval <= 0:
+            raise ValueError("heartbeat_interval must be > 0")
+
+        self.app_id = app_id
+        self.app_secret = app_secret
+        self.public_key = public_key
+        self.heartbeat_mode = mode
+        self.heartbeat_interval = int(heartbeat_interval)
+        self.api_base_url = api_base_url.rstrip("/")
+        self.on_failure = on_failure
+        self.request_timeout = request_timeout
+        # None / 0 / negative means "let the server pick its default (24h)".
+        # Server clamps to [3600, 604800]; we don't duplicate the clamp here.
+        self.ttl_seconds: Optional[int] = (
+            int(ttl_seconds) if isinstance(ttl_seconds, int) and ttl_seconds > 0 else None
+        )
+
+        self._lock = threading.Lock()
+        self._heartbeat_thread: Optional[threading.Thread] = None
+        self._heartbeat_started = False
+        self._heartbeat_stop = threading.Event()
+
+        self._license_key: Optional[str] = None
+        self._session_token: Optional[str] = None
+        self._session_expires_in: Optional[int] = None
+        self._last_nonce: Optional[str] = None
+        self._raw_payload_b64: Optional[str] = None
+        self._signature: Optional[str] = None
+        self._key_id: Optional[str] = None
+        self._session_data: Optional[Dict[str, Any]] = None
+        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._ed25519_public_key = self._load_public_key(public_key)
+
+    def login(self, license_key: str) -> bool:
+        if not license_key or not isinstance(license_key, str):
+            raise ValueError("license_key must be a non-empty string")
+
+        try:
+            self._validate_and_store(license_key)
+            self._start_heartbeat_once()
+            return True
+        except Exception as exc:
+            self._fail("login_failed", exc)
+            return False
+
+    def _start_heartbeat_once(self) -> None:
+        with self._lock:
+            if self._heartbeat_started:
+                return
+            self._heartbeat_stop.clear()
+            self._heartbeat_started = True
+            self._heartbeat_thread = threading.Thread(
+                target=self._heartbeat_loop,
+                name="AuthForgeHeartbeat",
+                daemon=True,
+            )
+            self._heartbeat_thread.start()
+
+    def _heartbeat_loop(self) -> None:
+        while not self._heartbeat_stop.wait(self.heartbeat_interval):
+            try:
+                if self.heartbeat_mode == "SERVER":
+                    self._server_heartbeat()
+                else:
+                    self._local_heartbeat()
+            except Exception as exc:
+                self._fail("heartbeat_failed", exc)
+                break
+
+    def _server_heartbeat(self) -> None:
+        with self._lock:
+            session_token = self._session_token
+            hwid = self._hwid
+        if not session_token:
+            raise RuntimeError("missing_session_token")
+
+        body = {
+            "appId": self.app_id,
+            "sessionToken": session_token,
+            "nonce": self._generate_nonce(),
+            "hwid": hwid,
+        }
+        response_obj = self._post_json("/auth/heartbeat", body)
+        expected_nonce = str(body.get("nonce", "")).strip()
+        self._apply_signed_response(
+            response_obj,
+            expected_nonce=expected_nonce,
+            license_key=None,
+            context="heartbeat",
+        )
+
+    def _local_heartbeat(self) -> None:
+        with self._lock:
+            raw_payload_b64 = self._raw_payload_b64
+            signature = self._signature
+            expires_in = self._session_expires_in
+        if not raw_payload_b64 or not signature:
+            raise RuntimeError("missing_local_verification_state")
+
+        self._verify_signature(raw_payload_b64, signature)
+
+        if expires_in is None:
+            raise RuntimeError("missing_session_expiry")
+
+        now = int(time.time())
+        if now >= int(expires_in):
+            raise RuntimeError("session_expired")
+
+    def _validate_and_store(self, license_key: str) -> None:
+        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)
+        expected_nonce = str(body.get("nonce", "")).strip()
+        self._apply_signed_response(
+            response_obj,
+            expected_nonce=expected_nonce,
+            license_key=license_key,
+            context="validate",
+        )
+
+    def _apply_signed_response(
+        self,
+        response_obj: Dict[str, Any],
+        expected_nonce: str,
+        license_key: Optional[str],
+        context: str,
+    ) -> None:
+        status = response_obj.get("status")
+        if not self._is_success_status(status):
+            error_code = self._extract_server_error(response_obj)
+            raise ValueError(error_code)
+
+        raw_payload_b64 = self._require_str(response_obj, "payload")
+        signature = self._require_str(response_obj, "signature")
+        payload_json = self._decode_payload_json(raw_payload_b64)
+
+        received_nonce = str(payload_json.get("nonce", "")).strip()
+        if received_nonce != expected_nonce:
+            raise ValueError("nonce_mismatch")
+
+        self._verify_signature(raw_payload_b64, signature)
+
+        session_token = str(payload_json.get("sessionToken", "")).strip()
+        if not session_token:
+            raise ValueError("missing_sessionToken")
+        key_id = response_obj.get("keyId")
+        if key_id is not None and not isinstance(key_id, str):
+            raise ValueError("invalid_keyId")
+
+        expires_from_token = self._extract_expires_in_from_session_token(session_token)
+        expires_from_payload = payload_json.get("expiresIn")
+
+        expires_in = expires_from_token
+        if expires_in is None and expires_from_payload is not None:
+            expires_in = int(expires_from_payload)
+        if expires_in is None:
+            raise ValueError("missing_expiresIn")
+
+        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._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._authenticated = True
+
+    def _post_json(self, path: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.api_base_url}{path}"
+        body = dict(data)
+        rate_attempt = 0
+        while True:
+            if rate_attempt > 0 and "nonce" in body:
+                body["nonce"] = self._generate_nonce()
+
+            network_attempt = 0
+            while True:
+                payload_bytes = json.dumps(body, separators=(",", ":")).encode("utf-8")
+                request = urllib.request.Request(
+                    url=url,
+                    data=payload_bytes,
+                    headers={"Content-Type": "application/json"},
+                    method="POST",
+                )
+                try:
+                    with urllib.request.urlopen(request, timeout=self.request_timeout) as response:
+                        raw_response = response.read().decode("utf-8")
+                        status_code = int(getattr(response, "status", 200))
+                    obj = self._parse_response_object(raw_response)
+                    data.clear()
+                    data.update(body)
+                    break
+                except urllib.error.HTTPError as exc:
+                    status_code = int(exc.code)
+                    try:
+                        detail = exc.read().decode("utf-8")
+                        obj = self._parse_response_object(detail)
+                    except Exception:
+                        raise RuntimeError(f"http_error_{status_code}") from exc
+                    data.clear()
+                    data.update(body)
+                    break
+                except (urllib.error.URLError, socket.timeout, TimeoutError) as exc:
+                    if network_attempt == 0:
+                        network_attempt += 1
+                        time.sleep(NETWORK_RETRY_DELAY)
+                        continue
+                    self._fail("network_error", exc)
+                    raise RuntimeError(f"url_error: {exc}") from exc
+
+            is_rate_limited = (
+                status_code == 429
+                or self._extract_server_error(obj) == "rate_limited"
+            )
+            if is_rate_limited and rate_attempt < len(RATE_LIMIT_RETRY_DELAYS):
+                time.sleep(RATE_LIMIT_RETRY_DELAYS[rate_attempt])
+                rate_attempt += 1
+                continue
+            return obj
+
+    def _parse_response_object(self, raw_response: str) -> Dict[str, Any]:
+        try:
+            obj = json.loads(raw_response)
+        except json.JSONDecodeError as exc:
+            raise ValueError("invalid_json_response") from exc
+        if not isinstance(obj, dict):
+            raise ValueError("response_not_json_object")
+        return obj
+
+    def _get_hwid(self) -> str:
+        mac = self._safe_mac_address()
+        cpu = self._safe_cpu_info()
+        disk = self._safe_disk_serial()
+        material = f"mac:{mac}|cpu:{cpu}|disk:{disk}"
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+    def _safe_mac_address(self) -> str:
+        try:
+            return f"{uuid.getnode():012x}"
+        except Exception:
+            return "mac-unavailable"
+
+    def _safe_cpu_info(self) -> str:
+        try:
+            value = platform.processor() or platform.machine() or "cpu-unavailable"
+            return str(value)
+        except Exception:
+            return "cpu-unavailable"
+
+    def _safe_disk_serial(self) -> str:
+        system = platform.system().lower()
+        try:
+            if "windows" in system:
+                return self._run_command(["wmic", "diskdrive", "get", "serialnumber"])
+            if "linux" in system:
+                out = self._run_command(["lsblk", "-ndo", "SERIAL"])
+                if out and out.strip():
+                    return out
+                return self._run_command(["udevadm", "info", "--query=property", "--name=sda"])
+            if "darwin" in system:
+                return self._run_command(["system_profiler", "SPStorageDataType"])
+        except Exception:
+            pass
+        return "disk-unavailable"
+
+    def _run_command(self, command: list[str]) -> str:
+        try:
+            output = subprocess.check_output(
+                command,
+                stderr=subprocess.DEVNULL,
+                timeout=2,
+            )
+            cleaned = " ".join(output.decode("utf-8", errors="ignore").split())
+            return cleaned[:256] if cleaned else "empty"
+        except Exception:
+            return "unavailable"
+
+    def _decode_payload_json(self, payload_b64: str) -> Dict[str, Any]:
+        payload_bytes = self._decode_base64_any(payload_b64)
+        try:
+            payload_obj = json.loads(payload_bytes.decode("utf-8"))
+        except Exception as exc:
+            raise ValueError("invalid_payload_json") from exc
+        if not isinstance(payload_obj, dict):
+            raise ValueError("payload_not_json_object")
+        return payload_obj
+
+    def _decode_base64_any(self, value: str) -> bytes:
+        padded = self._add_base64_padding(value)
+        try:
+            return base64.b64decode(padded, validate=False)
+        except Exception:
+            return base64.urlsafe_b64decode(padded)
+
+    def _extract_expires_in_from_session_token(self, session_token: str) -> Optional[int]:
+        payload = self._decode_session_token_body(session_token)
+        if payload is None:
+            return None
+        value = payload.get("exp")
+        if value is None:
+            return None
+        return int(value)
+
+    def _decode_session_token_body(self, session_token: str) -> Optional[Dict[str, Any]]:
+        parts = session_token.split(".")
+        if len(parts) < 2:
+            return None
+        padded = self._add_base64_padding(parts[0])
+        try:
+            decoded = base64.urlsafe_b64decode(padded)
+            payload = json.loads(decoded.decode("utf-8"))
+        except Exception:
+            return None
+        if not isinstance(payload, dict):
+            return None
+        return payload
+
+    def _add_base64_padding(self, text: str) -> str:
+        remainder = len(text) % 4
+        if remainder == 0:
+            return text
+        return text + ("=" * (4 - remainder))
+
+    def _load_public_key(self, public_key_b64: str) -> Ed25519PublicKey:
+        try:
+            public_key_bytes = base64.b64decode(
+                self._add_base64_padding(public_key_b64), validate=True
+            )
+        except Exception as exc:
+            raise ValueError("invalid_public_key") from exc
+        if len(public_key_bytes) != 32:
+            raise ValueError("invalid_public_key_length")
+        return Ed25519PublicKey.from_public_bytes(public_key_bytes)
+
+    def _verify_signature(self, raw_payload_b64: str, signature: str) -> None:
+        try:
+            signature_bytes = base64.b64decode(
+                self._add_base64_padding(signature), validate=True
+            )
+        except Exception as exc:
+            raise ValueError("invalid_signature_encoding") from exc
+        try:
+            self._ed25519_public_key.verify(
+                signature_bytes,
+                raw_payload_b64.encode("utf-8"),
+            )
+        except InvalidSignature as exc:
+            raise ValueError("signature_mismatch") from exc
+
+    def _generate_nonce(self) -> str:
+        return secrets.token_hex(16)
+
+    def _is_success_status(self, status: Any) -> bool:
+        if isinstance(status, bool):
+            return status
+        if status is None:
+            return False
+        value = str(status).strip().lower()
+        return value in {"ok", "success", "valid", "true", "1"}
+
+    def _require_str(self, obj: Dict[str, Any], key: str) -> str:
+        value = obj.get(key)
+        if value is None:
+            raise ValueError(f"missing_{key}")
+        text = str(value)
+        if not text:
+            raise ValueError(f"empty_{key}")
+        return text
+
+    def _extract_server_error(self, obj: Dict[str, Any]) -> str:
+        raw_error = str(obj.get("error", "")).strip().lower()
+        if raw_error in KNOWN_SERVER_ERRORS:
+            return raw_error
+        status = str(obj.get("status", "")).strip().lower()
+        if status in KNOWN_SERVER_ERRORS:
+            return status
+        return "unknown_error"
+
+    def _extract_optional_map(self, value: Any) -> Optional[Dict[str, Any]]:
+        if isinstance(value, dict):
+            return dict(value)
+        return None
+
+    def _fail(self, reason: str, exc: Optional[Exception] = None) -> None:
+        if self.on_failure is not None:
+            try:
+                self.on_failure(reason, exc)
+                return
+            except Exception:
+                pass
+        os._exit(1)
+
+    def logout(self) -> None:
+        self._heartbeat_stop.set()
+        with self._lock:
+            self._license_key = None
+            self._session_token = None
+            self._session_expires_in = None
+            self._last_nonce = None
+            self._raw_payload_b64 = None
+            self._signature = None
+            self._key_id = None
+            self._session_data = None
+            self._app_variables = None
+            self._license_variables = None
+            self._authenticated = False
+            self._heartbeat_started = False
+            self._heartbeat_thread = None
+
+    def is_authenticated(self) -> bool:
+        with self._lock:
+            return self._authenticated and bool(self._session_token)
+
+    def get_session_data(self) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            return dict(self._session_data) if self._session_data is not None else None
+
+    def get_app_variables(self) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            return dict(self._app_variables) if self._app_variables is not None else None
+
+    def get_license_variables(self) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            return dict(self._license_variables) if self._license_variables is not None else None

authforge_sdk-1.0.0/authforge_sdk.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: authforge-sdk
+Version: 1.0.0
+Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
+Author: AuthForge
+License: MIT
+Project-URL: Homepage, https://authforge.cc
+Project-URL: Documentation, https://docs.authforge.cc
+Project-URL: Source, https://github.com/AuthForgeCC/authforge-python
+Project-URL: Issues, https://github.com/AuthForgeCC/authforge-python/issues
+Keywords: authforge,license,licensing,hwid,authentication
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0.0
+Dynamic: license-file
+
+# AuthForge Python SDK
+
+Official Python SDK for [AuthForge](https://authforge.cc) — credit-based license key authentication with Ed25519-verified responses.
+
+Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
+
+## Installation
+
+The distribution on [PyPI](https://pypi.org/project/authforge-sdk/) is **`authforge-sdk`** (same idea as scoped npm names: install name ≠ import path). After installing, import the **`authforge`** module:
+
+```bash
+pip install authforge-sdk
+```
+
+**Alternative:** copy `authforge.py` into your project if you need a single-file vendored layout (you must still satisfy the `cryptography` dependency yourself).
+
+## Quick Start
+
+After **`pip install authforge-sdk`** (or vendoring `authforge.py`), use:
+
+```python
+from authforge import AuthForgeClient
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",           # from your AuthForge dashboard
+    app_secret="YOUR_APP_SECRET",   # from your AuthForge dashboard
+    public_key="YOUR_PUBLIC_KEY",   # from your AuthForge dashboard
+    heartbeat_mode="SERVER",        # "SERVER" or "LOCAL"
+)
+
+license_key = input("Enter license key: ")
+
+if client.login(license_key):
+    print("Authenticated!")
+    # Your app logic here — heartbeats run automatically in the background
+else:
+    print("Invalid license key.")
+    exit(1)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app_id` | str | required | Your application ID from the AuthForge dashboard |
+| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `public_key` | str | required | App Ed25519 public key (base64) from dashboard |
+| `heartbeat_mode` | str | required | `"SERVER"` or `"LOCAL"` (see below) |
+| `heartbeat_interval` | int | `900` | Seconds between heartbeat checks (any value ≥ 1; default 15 min) |
+| `api_base_url` | str | `https://auth.authforge.cc` | API endpoint |
+| `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. |
+
+## Billing
+
+- **1 `login()` call = 1 credit** (one `/auth/validate` debit).
+- **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).
+
+## Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `login(license_key)` | `bool` | Validates key and stores signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
+| `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 |
+| `get_app_variables()` | `dict \| None` | App-scoped variables map |
+| `get_license_variables()` | `dict \| None` | License-scoped variables map |
+
+## Heartbeat Modes
+
+**SERVER** — The SDK calls `/auth/heartbeat` every `heartbeat_interval` seconds with a fresh nonce, verifies signature + nonce, and triggers failure on invalid session state.
+
+**LOCAL** — No network calls. The SDK re-verifies stored signature state and checks expiry timestamp locally. If expired, it triggers failure with `session_expired`.
+
+## Failure Handling
+
+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`
+
+Request retries are automatic inside the internal HTTP layer:
+- `rate_limited`: retry after 2s, then 5s (max 3 attempts total)
+- network failure: retry once after 2s
+- every retry regenerates a fresh nonce
+
+```python
+def handle_auth_failure(reason, exception):
+    print(f"Auth failed: {reason}")
+    if exception:
+        print(f"Details: {exception}")
+    # Clean up and exit gracefully
+    sys.exit(1)
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",
+    public_key="YOUR_PUBLIC_KEY",
+    heartbeat_mode="SERVER",
+    on_failure=handle_auth_failure,
+)
+```
+
+## 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.
+
+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.
+
+3. **Crypto** — Both `/validate` and `/heartbeat` responses are signed by AuthForge with your app's Ed25519 private key. The SDK verifies every signed `payload` using your configured `public_key` and rejects tampered responses.
+
+## Hardware ID
+
+The SDK generates a deterministic hardware fingerprint by hashing:
+- MAC address
+- CPU identifier
+- Disk serial number
+
+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.
+
+## Test Vectors
+
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior.
+
+## Requirements
+
+- Python 3.9+
+- Dependency: `cryptography`
+
+## License
+
+MIT

authforge_sdk-1.0.0/authforge_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+authforge.py
+pyproject.toml
+authforge_sdk.egg-info/PKG-INFO
+authforge_sdk.egg-info/SOURCES.txt
+authforge_sdk.egg-info/dependency_links.txt
+authforge_sdk.egg-info/requires.txt
+authforge_sdk.egg-info/top_level.txt

authforge_sdk-1.0.0/authforge_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

authforge_sdk-1.0.0/authforge_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=41.0.0

authforge_sdk-1.0.0/authforge_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+authforge

authforge_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "authforge-sdk"
+version = "1.0.0"
+description = "Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AuthForge" }]
+keywords = ["authforge", "license", "licensing", "hwid", "authentication"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["cryptography>=41.0.0"]
+
+[project.urls]
+Homepage = "https://authforge.cc"
+Documentation = "https://docs.authforge.cc"
+Source = "https://github.com/AuthForgeCC/authforge-python"
+Issues = "https://github.com/AuthForgeCC/authforge-python/issues"
+
+[tool.setuptools]
+py-modules = ["authforge"]

authforge_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+