authforge-sdk 1.4.1__tar.gz → 2.0.0__tar.gz

{authforge_sdk-1.4.1/authforge_sdk.egg-info → authforge_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.4.1
+Version: 2.0.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -38,7 +38,7 @@ Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
 2. **Run through the grace period.** By default the app keeps running on the signed session with no further network calls. A background check re-verifies the signature locally and fails when the session TTL expires. The grace period equals the session TTL: default 24h, and the server clamps requested values to 1h to 7d.
 3. **Optionally enable online check-ins.** With `online_heartbeat=True`, the SDK also calls `POST /auth/heartbeat` every `heartbeat_interval` seconds for fast revocation and concurrent-use detection.
 
-Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge).
+Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge). If the machine can go online **once**, the end user can get that file themselves with `activate_offline()`: see [Self-serve offline activation](#self-serve-offline-activation).
 
 ## Features
 
@@ -50,8 +50,9 @@ Everything in this list ships in `authforge.py` today:
 - **Grace period by default**: after one successful activation, the app runs on the signed session (no network) until the TTL expires.
 - **Online check-ins** (opt-in): periodic `/auth/heartbeat` calls for fast revocation and concurrent-use detection.
 - **Offline license files (`.authforge`)**: `login_from_file()` / `verify_license_file()` verify a cloud-minted, Ed25519-signed file with zero network access for air-gapped machines.
+- **Self-serve offline activation**: `activate_offline()` turns a license key into a lifetime, HWID-bound `.authforge` file with one online call, then runs offline from that file.
 - **Nonce anti-replay**: a fresh 128-bit nonce is sent on every request and the echoed nonce in the signed payload is checked before the response is accepted.
-- **HWID fingerprinting**: deterministic device hash from MAC + CPU + disk serial, with graceful per-component fallback.
+- **HWID v2**: per-app device id derived from the OS machine id (macOS `IOPlatformUUID`, Linux `/etc/machine-id`, Windows `MachineGuid`), identical across all AuthForge SDKs for the same app and machine.
 - **`hwid_override`**: bind to any identity instead of the machine (for example `tg:<id>`, `discord:<id>`).
 - **Seat enforcement**: the server binds each HWID into a license's free slots up to `maxHwidSlots`; `hwid_count` / `max_hwid_slots` are surfaced on the result. A shared (unlimited-seat) key skips per-device binding.
 - **Self-ban** (`self_ban()`) for anti-tamper response, both pre-session and post-session.
@@ -118,7 +119,7 @@ client = AuthForgeClient(
 | `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) | The grace period duration: how long the app keeps running on the signed session without contacting AuthForge. Server clamps to `[3600, 604800]` (1h to 7d); preserved across check-in 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. |
+| `hwid_override` | `str \| None` | `None` | Optional custom hardware/subject identifier. When set to a non-empty value, the SDK uses it instead of deriving the HWID from the OS machine id. |
 | `online_heartbeat` | bool (keyword-only) | `False` | Enable online check-ins: periodic `POST /auth/heartbeat` for fast revocation and concurrent-use detection. |
 
 ### Identity-based binding example (Telegram/Discord)
@@ -189,12 +190,81 @@ if client.login_from_file("license.authforge"):
     print(client.get_license_variables())
 ```
 
-Collect the HWID from the same SDK build that will load the file: fingerprints are not portable across SDKs or languages. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
+Since 2.0 every AuthForge SDK computes the same HWID for the same app id and machine, but HWIDs collected before upgrading to 2.0 no longer match: collect the HWID again after upgrading. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
 
 `verify_license_file()` (module function and client method) performs the same checks without touching client state. Failure codes, in check order: `bad_armor`, `bad_signature`, `unsupported_version`, `malformed_payload`, `wrong_app`, `expired`, `hwid_mismatch`. `login_from_file()` reports them through `on_failure("offline_login_failed", exc)` and returns `False`; it never calls `os._exit`.
 
 File format (version 1): PEM-style armor with informational headers, a base64 JSON payload (`v`, `appId`, `licenseKey`, `jti`, `kid`, `issuedAt`, `expiresAt`, `hwid` policy, optional label/variable snapshots) and a detached Ed25519 signature over the UTF-8 bytes of the base64 payload string - the same contract as `/auth/validate`. See `offline_license_vectors.json` for conformance vectors.
 
+## Self-serve offline activation
+
+A separate mode for apps that sell a one-time license and then run with no network: the end user types the license key once, `activate_offline()` makes **one** online call (`POST /auth/offline/activate`) and gets back a lifetime `.authforge` file bound to this machine's HWID. From then on the app starts with `login_from_file()` and never contacts AuthForge again.
+
+How it differs from air-gapped offline files:
+
+- It **needs the App Secret**, because it is an online call. Air-gapped builds that only use `login_from_file()` still ship with `app_secret=None`.
+- The app owner opts the app in (app settings in the dashboard). Only **perpetual**, **seat-limited** licenses can self-serve; each license can produce files for at most `maxHwidSlots` distinct machines, ever. HWID resets do not free those machine slots.
+- **Billing:** a new machine costs the app owner **2 credits**, once. The same machine activating again (reinstall, deleted file) gets the identical file back for **free**. A refused activation costs nothing.
+- **A refund or chargeback revokes the license online but cannot reach files already issued.** A lifetime file keeps working on its machine.
+
+```python
+import os
+import sys
+
+from authforge import AuthForgeClient, AuthForgeError
+
+LICENSE_PATH = os.path.join(os.path.expanduser("~"), ".myapp", "license.authforge")
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",  # required for activate_offline (online call)
+    public_key="YOUR_PUBLIC_KEY",
+    on_failure=lambda reason, exc: None,  # login_from_file reports why it failed here
+)
+
+# 1. No network, no credits: run from the file if it is there and valid.
+if not (os.path.exists(LICENSE_PATH) and client.login_from_file(LICENSE_PATH)):
+    # 2. No file yet, or it fails (e.g. hwid_mismatch after a hardware change).
+    key = input("License key: ").strip()
+    try:
+        client.activate_offline(key, path=LICENSE_PATH)
+    except AuthForgeError as exc:
+        if exc.code == "offline_activation_limit_reached":
+            print("This license is active on its maximum number of machines. Please contact the vendor.")
+        elif exc.code in {"invalid_key", "revoked", "expired"}:
+            print("That license key is not valid.")
+        elif exc.code == "hwid_mismatch":
+            print("No free seat on this license for this machine.")
+        elif exc.transient:
+            print(f"Could not activate right now ({exc.code}). Check your connection and try again.")
+        else:
+            print(f"Activation failed: {exc.code}")
+        sys.exit(1)
+
+print("Licensed:", client.get_license_variables())
+```
+
+`activate_offline(license_key, path=None)` returns `True` on success and raises `AuthForgeError` otherwise. It:
+
+1. Fails fast with the usual "app_secret is required" `ValueError` (no request) when the client has no App Secret.
+2. Sends `appId`, `appSecret`, `licenseKey`, the same HWID `login()` sends and a fresh nonce, with the same retries as `login()` (`rate_limited` after 2s then 5s, one retry on a network error).
+3. Verifies the returned file with your public key(s), app id and this machine's HWID **before** writing anything. A file that fails raises `offline_file_rejected`; the message includes the verifier's reason (`bad_signature`, `wrong_app`, `hwid_mismatch`, ...).
+4. If `path` is set, writes the file byte-for-byte and atomically (temp file in the same directory, then rename), creating parent directories.
+5. Leaves the client authenticated exactly as `login_from_file()` does: `get_session_kind()` is `"offline"`, variables and `get_offline_license()` are set, no background checks start. `get_offline_license()["replay"]` is `True` when the server returned a file this machine already had.
+
+On any failure nothing is written to `path` (an existing file there is left as it was), the call does not authenticate the client (an existing session is kept), and neither `on_failure` nor `os._exit` is called.
+
+| Code | Kind | Meaning |
+| --- | --- | --- |
+| `offline_activation_disabled` | fatal | The app has not opted in to self-serve activation |
+| `offline_activation_requires_perpetual` | fatal | The license has an expiry; only perpetual licenses can self-serve |
+| `offline_activation_requires_seats` | fatal | Unlimited-seat (shared) licenses cannot self-serve |
+| `offline_activation_limit_reached` | fatal | Every machine slot on the license is used; the buyer must contact the vendor |
+| `offline_file_rejected` | fatal | SDK code: the returned file failed local verification; nothing was written |
+| `hwid_mismatch` | fatal | No free seat on the license for this machine (server code, not the verifier's) |
+| `file_write_failed` | transient | The verified file could not be written to `path`; activating again is free |
+| `invalid_key`, `revoked`, `expired`, `no_credits`, `rate_limited`, `unexpected_response`, `network_error`, ... | as everywhere else | Existing codes keep their meaning and classification |
+
 ## Migrating from heartbeat_mode
 
 Earlier releases required `heartbeat_mode="LOCAL"` or `"SERVER"`. The argument is now optional and deprecated; it still works but emits a `DeprecationWarning`.
@@ -217,6 +287,7 @@ For code that still reads it, `client.heartbeat_mode` remains available and refl
 
 - **1 `login()` or `validate_license()` call = 1 credit** (one `/auth/validate` debit each).
 - **10 online check-ins on the same license = 1 credit** (billed every 10th successful `/auth/heartbeat`). Grace period checks are local and free.
+- **1 new offline activation (`activate_offline()`) = 2 credits**, charged to the app owner; re-activating the same machine is free. `login_from_file()` is always free.
 
 A desktop app running 6h/day with online check-ins at a 15-minute interval burns ~3-4 credits/day. The server enforces `/auth/heartbeat` at 6 requests/minute per license key, so keep intervals at 10 seconds or higher and pick the interval based on how fast you need revocations to propagate (they always land on the **next** check-in).
 
@@ -226,8 +297,9 @@ A desktop app running 6h/day with online check-ins at a 15-minute interval burns
 |---|---|---|
 | `login(license_key)` | `bool` | Activates: validates the key online and stores the signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
 | `validate_license(license_key)` | `ValidateLicenseResult` | Same `/auth/validate` + signatures as `login`; does not store session or start background checks; 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) |
+| `self_ban(...)` | `dict` | Requests `/auth/selfban` to blacklist HWID/IP and optionally revoke (session-authenticated only). Raises `ValueError` on any failure (a network failure as `AuthForgeError` `network_error` / `timeout`); never calls `on_failure` or `os._exit` |
 | `login_from_file(path_or_text)` | `bool` | Authorizes from an offline `.authforge` file with no network; never starts background checks; failures go to `on_failure("offline_login_failed", …)` |
+| `activate_offline(license_key, path=None)` | `bool` | Self-serve offline activation: one online call returns a lifetime HWID-bound `.authforge` file, verified locally, written atomically to `path` and applied like `login_from_file`. Needs the App Secret; raises `AuthForgeError` on refusal; never calls `on_failure` or `os._exit` |
 | `verify_license_file(path_or_text, *, now=None)` | `VerifyLicenseFileResult` | Verifies a `.authforge` file with this client's app id / keys / HWID without changing state |
 | `get_offline_license()` | `dict \| None` | Metadata of the offline file in use (`jti`, `expires_at`, `hwid_policy`, …) |
 | `get_session_kind()` | `"online" \| "offline" \| None` | Which kind of session the client holds (`None` when logged out) |
@@ -247,7 +319,11 @@ If authentication fails (activation rejected, check-in fails, signature mismatch
 **`validate_license()`** does not trigger `on_failure` or `os._exit`: check `result["valid"]` and `result["code"]`.
 
 Recognized server errors (`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`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`. Codes added to the server later are passed through unchanged.
+`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `app_burn_cap_reached`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`, and from `activate_offline()`: `offline_activation_disabled`, `offline_activation_requires_perpetual`, `offline_activation_requires_seats`, `offline_activation_limit_reached`, plus the SDK code `offline_file_rejected`. Codes added to the server later are passed through unchanged.
+
+**`activate_offline()`** does not trigger `on_failure` or `os._exit` either: it raises `AuthForgeError` (see [Self-serve offline activation](#self-serve-offline-activation)).
+
+**`self_ban()`** does not trigger `on_failure` or `os._exit` either: every failure raises, a server rejection as `ValueError(code)` and a network failure as `AuthForgeError` with `exc.code` `network_error` or `timeout`.
 
 Request retries are automatic inside the internal HTTP layer:
 - `rate_limited`, or HTTP 429 with no error code: retry after 2s, then 5s (max 3 attempts total)
@@ -266,10 +342,10 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 
 | Kind | Codes | What the SDK does |
 |---|---|---|
-| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
+| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` (plus the `activate_offline()`-only codes `offline_activation_*` and `offline_file_rejected`) | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
 | Transient | Everything else: `network_error`, `timeout`, `rate_limited`, `system_error`, `no_credits`, `demo_quota_exceeded`, `app_burn_cap_reached`, `bad_request`, `invalid_key`, every `http_error_<status>`, `invalid_json_response`, `unexpected_response`, `nonce_mismatch`, any unrecognized code | Keeps the session and checks in again on the next `heartbeat_interval`. Once the signed session's TTL has passed, the next transient failure is reported as a fatal `session_expired` instead. |
 
-Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Heartbeat network failures are reported once, as `heartbeat_failed` with code `network_error` or `timeout`, not as a separate `network_error` reason.
+Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Network failures are reported once, with code `network_error` or `timeout`: as `heartbeat_failed` from check-ins and as `login_failed` from `login()`, never as a separate `network_error` reason. `activate_offline()` and `self_ban()` raise them as `AuthForgeError` instead.
 
 `on_failure` runs on the background heartbeat thread with no SDK lock held, so calling `logout()`, `is_authenticated()` or `login()` from it is safe. A check-in that is still in flight when you call `logout()` or `login()` is discarded: it cannot restore the old session or report a failure for it.
 
@@ -339,11 +415,12 @@ client.self_ban(
 - 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.
+- Every failure raises: a server rejection as `ValueError(code)`, a network failure (after one retry) as `AuthForgeError` with `exc.code` `network_error` or `timeout`. `self_ban()` never calls `on_failure` or `os._exit`, with or without a callback.
 - Not available after `login_from_file()`: offline sessions have no server session, so `self_ban()` with no explicit `license_key` / `session_token` raises `ValueError("offline_session")` without contacting the server.
 
 ## How It Works
 
-1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
+1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it derives the HWID from the OS machine id (see [Hardware ID](#hardware-id)). 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
 
 2. **Background checks**: a daemon thread wakes at the configured interval. By default it enforces the grace period: it re-verifies the stored signature and checks expiry without network calls. With `online_heartbeat=True`, it instead sends `/auth/heartbeat` with a fresh nonce and verifies the response.
 
@@ -351,18 +428,29 @@ client.self_ban(
 
 ## Hardware ID
 
-The SDK generates a deterministic hardware fingerprint by hashing:
-- MAC address
-- CPU identifier
-- Disk serial number
+The HWID (v2, since 2.0) is
+
+`SHA256("authforge-hwid-v2|" + app_id + "|" + machine_id)` as lowercase hex,
+
+where `machine_id` is the operating system's own machine id, trimmed and lowercased:
+
+| OS | Source |
+| -- | ------ |
+| macOS | `IOPlatformUUID` (`/usr/sbin/ioreg -rd1 -c IOPlatformExpertDevice`) |
+| Linux | `/etc/machine-id`, then `/var/lib/dbus/machine-id` |
+| Windows | `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` (64-bit registry view, via `winreg`) |
+
+These ids survive network changes, renames, disk usage and USB devices. Including the app id means two different apps on the same machine get unrelated HWIDs. Every AuthForge SDK computes the same value for the same app id and machine; `hwid_vectors.json` pins this. The HWID is sent with every auth request so the server can enforce per-device license limits.
+
+If no valid OS id can be read (for example a container without `/etc/machine-id`), the SDK falls back to `legacy:<the pre-2.0 fingerprint of MAC, CPU and disk serial>` as the machine id. Containers built from one image can also share a baked-in machine id, so for containers prefer `hwid_override` with an identifier you control.
 
-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.
+The helpers `hwid_from_machine_id`, `normalize_machine_id`, `parse_ioreg_platform_uuid` and `parse_reg_query_machine_guid` are exported for tooling and tests.
 
 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. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects.
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects. `self_serve_activation_vectors.json` is the cross-SDK suite for `activate_offline()`: mocked `/auth/offline/activate` responses with the expected written file, session and error code. `hwid_vectors.json` (generated by `authforge-node/generate_hwid_vectors.mjs`) is the cross-SDK suite for HWID v2: derivation, machine id normalization, and the `ioreg` / `reg query` parsers.
 
 ## Requirements
 

{authforge_sdk-1.4.1 → authforge_sdk-2.0.0}/README.md

@@ -10,7 +10,7 @@ Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
 2. **Run through the grace period.** By default the app keeps running on the signed session with no further network calls. A background check re-verifies the signature locally and fails when the session TTL expires. The grace period equals the session TTL: default 24h, and the server clamps requested values to 1h to 7d.
 3. **Optionally enable online check-ins.** With `online_heartbeat=True`, the SDK also calls `POST /auth/heartbeat` every `heartbeat_interval` seconds for fast revocation and concurrent-use detection.
 
-Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge).
+Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge). If the machine can go online **once**, the end user can get that file themselves with `activate_offline()`: see [Self-serve offline activation](#self-serve-offline-activation).
 
 ## Features
 
@@ -22,8 +22,9 @@ Everything in this list ships in `authforge.py` today:
 - **Grace period by default**: after one successful activation, the app runs on the signed session (no network) until the TTL expires.
 - **Online check-ins** (opt-in): periodic `/auth/heartbeat` calls for fast revocation and concurrent-use detection.
 - **Offline license files (`.authforge`)**: `login_from_file()` / `verify_license_file()` verify a cloud-minted, Ed25519-signed file with zero network access for air-gapped machines.
+- **Self-serve offline activation**: `activate_offline()` turns a license key into a lifetime, HWID-bound `.authforge` file with one online call, then runs offline from that file.
 - **Nonce anti-replay**: a fresh 128-bit nonce is sent on every request and the echoed nonce in the signed payload is checked before the response is accepted.
-- **HWID fingerprinting**: deterministic device hash from MAC + CPU + disk serial, with graceful per-component fallback.
+- **HWID v2**: per-app device id derived from the OS machine id (macOS `IOPlatformUUID`, Linux `/etc/machine-id`, Windows `MachineGuid`), identical across all AuthForge SDKs for the same app and machine.
 - **`hwid_override`**: bind to any identity instead of the machine (for example `tg:<id>`, `discord:<id>`).
 - **Seat enforcement**: the server binds each HWID into a license's free slots up to `maxHwidSlots`; `hwid_count` / `max_hwid_slots` are surfaced on the result. A shared (unlimited-seat) key skips per-device binding.
 - **Self-ban** (`self_ban()`) for anti-tamper response, both pre-session and post-session.
@@ -90,7 +91,7 @@ client = AuthForgeClient(
 | `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) | The grace period duration: how long the app keeps running on the signed session without contacting AuthForge. Server clamps to `[3600, 604800]` (1h to 7d); preserved across check-in 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. |
+| `hwid_override` | `str \| None` | `None` | Optional custom hardware/subject identifier. When set to a non-empty value, the SDK uses it instead of deriving the HWID from the OS machine id. |
 | `online_heartbeat` | bool (keyword-only) | `False` | Enable online check-ins: periodic `POST /auth/heartbeat` for fast revocation and concurrent-use detection. |
 
 ### Identity-based binding example (Telegram/Discord)
@@ -161,12 +162,81 @@ if client.login_from_file("license.authforge"):
     print(client.get_license_variables())
 ```
 
-Collect the HWID from the same SDK build that will load the file: fingerprints are not portable across SDKs or languages. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
+Since 2.0 every AuthForge SDK computes the same HWID for the same app id and machine, but HWIDs collected before upgrading to 2.0 no longer match: collect the HWID again after upgrading. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
 
 `verify_license_file()` (module function and client method) performs the same checks without touching client state. Failure codes, in check order: `bad_armor`, `bad_signature`, `unsupported_version`, `malformed_payload`, `wrong_app`, `expired`, `hwid_mismatch`. `login_from_file()` reports them through `on_failure("offline_login_failed", exc)` and returns `False`; it never calls `os._exit`.
 
 File format (version 1): PEM-style armor with informational headers, a base64 JSON payload (`v`, `appId`, `licenseKey`, `jti`, `kid`, `issuedAt`, `expiresAt`, `hwid` policy, optional label/variable snapshots) and a detached Ed25519 signature over the UTF-8 bytes of the base64 payload string - the same contract as `/auth/validate`. See `offline_license_vectors.json` for conformance vectors.
 
+## Self-serve offline activation
+
+A separate mode for apps that sell a one-time license and then run with no network: the end user types the license key once, `activate_offline()` makes **one** online call (`POST /auth/offline/activate`) and gets back a lifetime `.authforge` file bound to this machine's HWID. From then on the app starts with `login_from_file()` and never contacts AuthForge again.
+
+How it differs from air-gapped offline files:
+
+- It **needs the App Secret**, because it is an online call. Air-gapped builds that only use `login_from_file()` still ship with `app_secret=None`.
+- The app owner opts the app in (app settings in the dashboard). Only **perpetual**, **seat-limited** licenses can self-serve; each license can produce files for at most `maxHwidSlots` distinct machines, ever. HWID resets do not free those machine slots.
+- **Billing:** a new machine costs the app owner **2 credits**, once. The same machine activating again (reinstall, deleted file) gets the identical file back for **free**. A refused activation costs nothing.
+- **A refund or chargeback revokes the license online but cannot reach files already issued.** A lifetime file keeps working on its machine.
+
+```python
+import os
+import sys
+
+from authforge import AuthForgeClient, AuthForgeError
+
+LICENSE_PATH = os.path.join(os.path.expanduser("~"), ".myapp", "license.authforge")
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",  # required for activate_offline (online call)
+    public_key="YOUR_PUBLIC_KEY",
+    on_failure=lambda reason, exc: None,  # login_from_file reports why it failed here
+)
+
+# 1. No network, no credits: run from the file if it is there and valid.
+if not (os.path.exists(LICENSE_PATH) and client.login_from_file(LICENSE_PATH)):
+    # 2. No file yet, or it fails (e.g. hwid_mismatch after a hardware change).
+    key = input("License key: ").strip()
+    try:
+        client.activate_offline(key, path=LICENSE_PATH)
+    except AuthForgeError as exc:
+        if exc.code == "offline_activation_limit_reached":
+            print("This license is active on its maximum number of machines. Please contact the vendor.")
+        elif exc.code in {"invalid_key", "revoked", "expired"}:
+            print("That license key is not valid.")
+        elif exc.code == "hwid_mismatch":
+            print("No free seat on this license for this machine.")
+        elif exc.transient:
+            print(f"Could not activate right now ({exc.code}). Check your connection and try again.")
+        else:
+            print(f"Activation failed: {exc.code}")
+        sys.exit(1)
+
+print("Licensed:", client.get_license_variables())
+```
+
+`activate_offline(license_key, path=None)` returns `True` on success and raises `AuthForgeError` otherwise. It:
+
+1. Fails fast with the usual "app_secret is required" `ValueError` (no request) when the client has no App Secret.
+2. Sends `appId`, `appSecret`, `licenseKey`, the same HWID `login()` sends and a fresh nonce, with the same retries as `login()` (`rate_limited` after 2s then 5s, one retry on a network error).
+3. Verifies the returned file with your public key(s), app id and this machine's HWID **before** writing anything. A file that fails raises `offline_file_rejected`; the message includes the verifier's reason (`bad_signature`, `wrong_app`, `hwid_mismatch`, ...).
+4. If `path` is set, writes the file byte-for-byte and atomically (temp file in the same directory, then rename), creating parent directories.
+5. Leaves the client authenticated exactly as `login_from_file()` does: `get_session_kind()` is `"offline"`, variables and `get_offline_license()` are set, no background checks start. `get_offline_license()["replay"]` is `True` when the server returned a file this machine already had.
+
+On any failure nothing is written to `path` (an existing file there is left as it was), the call does not authenticate the client (an existing session is kept), and neither `on_failure` nor `os._exit` is called.
+
+| Code | Kind | Meaning |
+| --- | --- | --- |
+| `offline_activation_disabled` | fatal | The app has not opted in to self-serve activation |
+| `offline_activation_requires_perpetual` | fatal | The license has an expiry; only perpetual licenses can self-serve |
+| `offline_activation_requires_seats` | fatal | Unlimited-seat (shared) licenses cannot self-serve |
+| `offline_activation_limit_reached` | fatal | Every machine slot on the license is used; the buyer must contact the vendor |
+| `offline_file_rejected` | fatal | SDK code: the returned file failed local verification; nothing was written |
+| `hwid_mismatch` | fatal | No free seat on the license for this machine (server code, not the verifier's) |
+| `file_write_failed` | transient | The verified file could not be written to `path`; activating again is free |
+| `invalid_key`, `revoked`, `expired`, `no_credits`, `rate_limited`, `unexpected_response`, `network_error`, ... | as everywhere else | Existing codes keep their meaning and classification |
+
 ## Migrating from heartbeat_mode
 
 Earlier releases required `heartbeat_mode="LOCAL"` or `"SERVER"`. The argument is now optional and deprecated; it still works but emits a `DeprecationWarning`.
@@ -189,6 +259,7 @@ For code that still reads it, `client.heartbeat_mode` remains available and refl
 
 - **1 `login()` or `validate_license()` call = 1 credit** (one `/auth/validate` debit each).
 - **10 online check-ins on the same license = 1 credit** (billed every 10th successful `/auth/heartbeat`). Grace period checks are local and free.
+- **1 new offline activation (`activate_offline()`) = 2 credits**, charged to the app owner; re-activating the same machine is free. `login_from_file()` is always free.
 
 A desktop app running 6h/day with online check-ins at a 15-minute interval burns ~3-4 credits/day. The server enforces `/auth/heartbeat` at 6 requests/minute per license key, so keep intervals at 10 seconds or higher and pick the interval based on how fast you need revocations to propagate (they always land on the **next** check-in).
 
@@ -198,8 +269,9 @@ A desktop app running 6h/day with online check-ins at a 15-minute interval burns
 |---|---|---|
 | `login(license_key)` | `bool` | Activates: validates the key online and stores the signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
 | `validate_license(license_key)` | `ValidateLicenseResult` | Same `/auth/validate` + signatures as `login`; does not store session or start background checks; 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) |
+| `self_ban(...)` | `dict` | Requests `/auth/selfban` to blacklist HWID/IP and optionally revoke (session-authenticated only). Raises `ValueError` on any failure (a network failure as `AuthForgeError` `network_error` / `timeout`); never calls `on_failure` or `os._exit` |
 | `login_from_file(path_or_text)` | `bool` | Authorizes from an offline `.authforge` file with no network; never starts background checks; failures go to `on_failure("offline_login_failed", …)` |
+| `activate_offline(license_key, path=None)` | `bool` | Self-serve offline activation: one online call returns a lifetime HWID-bound `.authforge` file, verified locally, written atomically to `path` and applied like `login_from_file`. Needs the App Secret; raises `AuthForgeError` on refusal; never calls `on_failure` or `os._exit` |
 | `verify_license_file(path_or_text, *, now=None)` | `VerifyLicenseFileResult` | Verifies a `.authforge` file with this client's app id / keys / HWID without changing state |
 | `get_offline_license()` | `dict \| None` | Metadata of the offline file in use (`jti`, `expires_at`, `hwid_policy`, …) |
 | `get_session_kind()` | `"online" \| "offline" \| None` | Which kind of session the client holds (`None` when logged out) |
@@ -219,7 +291,11 @@ If authentication fails (activation rejected, check-in fails, signature mismatch
 **`validate_license()`** does not trigger `on_failure` or `os._exit`: check `result["valid"]` and `result["code"]`.
 
 Recognized server errors (`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`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`. Codes added to the server later are passed through unchanged.
+`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `app_burn_cap_reached`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`, and from `activate_offline()`: `offline_activation_disabled`, `offline_activation_requires_perpetual`, `offline_activation_requires_seats`, `offline_activation_limit_reached`, plus the SDK code `offline_file_rejected`. Codes added to the server later are passed through unchanged.
+
+**`activate_offline()`** does not trigger `on_failure` or `os._exit` either: it raises `AuthForgeError` (see [Self-serve offline activation](#self-serve-offline-activation)).
+
+**`self_ban()`** does not trigger `on_failure` or `os._exit` either: every failure raises, a server rejection as `ValueError(code)` and a network failure as `AuthForgeError` with `exc.code` `network_error` or `timeout`.
 
 Request retries are automatic inside the internal HTTP layer:
 - `rate_limited`, or HTTP 429 with no error code: retry after 2s, then 5s (max 3 attempts total)
@@ -238,10 +314,10 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 
 | Kind | Codes | What the SDK does |
 |---|---|---|
-| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
+| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` (plus the `activate_offline()`-only codes `offline_activation_*` and `offline_file_rejected`) | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
 | Transient | Everything else: `network_error`, `timeout`, `rate_limited`, `system_error`, `no_credits`, `demo_quota_exceeded`, `app_burn_cap_reached`, `bad_request`, `invalid_key`, every `http_error_<status>`, `invalid_json_response`, `unexpected_response`, `nonce_mismatch`, any unrecognized code | Keeps the session and checks in again on the next `heartbeat_interval`. Once the signed session's TTL has passed, the next transient failure is reported as a fatal `session_expired` instead. |
 
-Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Heartbeat network failures are reported once, as `heartbeat_failed` with code `network_error` or `timeout`, not as a separate `network_error` reason.
+Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Network failures are reported once, with code `network_error` or `timeout`: as `heartbeat_failed` from check-ins and as `login_failed` from `login()`, never as a separate `network_error` reason. `activate_offline()` and `self_ban()` raise them as `AuthForgeError` instead.
 
 `on_failure` runs on the background heartbeat thread with no SDK lock held, so calling `logout()`, `is_authenticated()` or `login()` from it is safe. A check-in that is still in flight when you call `logout()` or `login()` is discarded: it cannot restore the old session or report a failure for it.
 
@@ -311,11 +387,12 @@ client.self_ban(
 - 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.
+- Every failure raises: a server rejection as `ValueError(code)`, a network failure (after one retry) as `AuthForgeError` with `exc.code` `network_error` or `timeout`. `self_ban()` never calls `on_failure` or `os._exit`, with or without a callback.
 - Not available after `login_from_file()`: offline sessions have no server session, so `self_ban()` with no explicit `license_key` / `session_token` raises `ValueError("offline_session")` without contacting the server.
 
 ## How It Works
 
-1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
+1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it derives the HWID from the OS machine id (see [Hardware ID](#hardware-id)). 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
 
 2. **Background checks**: a daemon thread wakes at the configured interval. By default it enforces the grace period: it re-verifies the stored signature and checks expiry without network calls. With `online_heartbeat=True`, it instead sends `/auth/heartbeat` with a fresh nonce and verifies the response.
 
@@ -323,18 +400,29 @@ client.self_ban(
 
 ## Hardware ID
 
-The SDK generates a deterministic hardware fingerprint by hashing:
-- MAC address
-- CPU identifier
-- Disk serial number
+The HWID (v2, since 2.0) is
+
+`SHA256("authforge-hwid-v2|" + app_id + "|" + machine_id)` as lowercase hex,
+
+where `machine_id` is the operating system's own machine id, trimmed and lowercased:
+
+| OS | Source |
+| -- | ------ |
+| macOS | `IOPlatformUUID` (`/usr/sbin/ioreg -rd1 -c IOPlatformExpertDevice`) |
+| Linux | `/etc/machine-id`, then `/var/lib/dbus/machine-id` |
+| Windows | `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` (64-bit registry view, via `winreg`) |
+
+These ids survive network changes, renames, disk usage and USB devices. Including the app id means two different apps on the same machine get unrelated HWIDs. Every AuthForge SDK computes the same value for the same app id and machine; `hwid_vectors.json` pins this. The HWID is sent with every auth request so the server can enforce per-device license limits.
+
+If no valid OS id can be read (for example a container without `/etc/machine-id`), the SDK falls back to `legacy:<the pre-2.0 fingerprint of MAC, CPU and disk serial>` as the machine id. Containers built from one image can also share a baked-in machine id, so for containers prefer `hwid_override` with an identifier you control.
 
-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.
+The helpers `hwid_from_machine_id`, `normalize_machine_id`, `parse_ioreg_platform_uuid` and `parse_reg_query_machine_guid` are exported for tooling and tests.
 
 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. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects.
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects. `self_serve_activation_vectors.json` is the cross-SDK suite for `activate_offline()`: mocked `/auth/offline/activate` responses with the expected written file, session and error code. `hwid_vectors.json` (generated by `authforge-node/generate_hwid_vectors.mjs`) is the cross-SDK suite for HWID v2: derivation, machine id normalization, and the `ioreg` / `reg query` parsers.
 
 ## Requirements
 

{authforge_sdk-1.4.1 → authforge_sdk-2.0.0}/authforge.py

@@ -88,7 +88,7 @@ _ACTIVATION_REQUEST_VERSION = 1
 _ACTIVATION_REQUEST_TYP = "authforge-activation-request"
 _BEGIN_ACTIVATION_REQUEST = "-----BEGIN AUTHFORGE ACTIVATION REQUEST-----"
 _END_ACTIVATION_REQUEST = "-----END AUTHFORGE ACTIVATION REQUEST-----"
-_SDK_TAG = "python/1.4.1"
+_SDK_TAG = "python/2.0.0"
 _ARMOR_LINE_WIDTH = 64
 _MAX_REQUEST_HWID = 256
 _MAX_REQUEST_MACHINE_NAME = 128
@@ -477,6 +477,33 @@ def _verify_offline_signature(payload_base64: str, signature_base64: str, keys:
     return False
 
 
+def _write_file_atomic(path: str, data: bytes) -> None:
+    """Write ``data`` byte-for-byte to ``path`` via a temp file in the same
+    directory and ``os.replace``, creating parent directories. A failure never
+    leaves a partial file at ``path`` or changes an existing one."""
+    directory = os.path.dirname(os.path.abspath(path))
+    os.makedirs(directory, exist_ok=True)
+    tmp_path = os.path.join(
+        directory, f".{os.path.basename(path)}.{secrets.token_hex(8)}.tmp"
+    )
+    # O_BINARY (Windows only) keeps the bytes exact; mode 0o666 lets the umask
+    # apply as for a normal open().
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+    fd = os.open(tmp_path, flags, 0o666)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, path)
+    except BaseException:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
 KNOWN_SERVER_ERRORS = {
     "invalid_app",
     "invalid_key",
@@ -495,6 +522,14 @@ KNOWN_SERVER_ERRORS = {
     "malformed_request",
     "demo_quota_exceeded",
     "system_error",
+    # POST /auth/offline/activate (self-serve offline activation).
+    "offline_activation_disabled",
+    "offline_activation_requires_perpetual",
+    "offline_activation_requires_seats",
+    "offline_activation_limit_reached",
+    # SDK code (never sent by the server): the returned file failed local
+    # verification. Listed with the server codes for cross-SDK parity.
+    "offline_file_rejected",
 }
 
 # Well-formed AuthForge verdicts that end the session. This is the only list
@@ -510,6 +545,12 @@ DEFINITIVE_ERROR_CODES = frozenset(
         "app_disabled",
         "invalid_app",
         "signature_mismatch",
+        "offline_activation_disabled",
+        "offline_activation_requires_perpetual",
+        "offline_activation_requires_seats",
+        "offline_activation_limit_reached",
+        # SDK code: activate_offline() got a file that failed local verification.
+        "offline_file_rejected",
     }
 )
 
@@ -536,6 +577,9 @@ TRANSIENT_ERROR_CODES = frozenset(
         "missing_session_token",
         "nonce_mismatch",
         "unknown_error",
+        # activate_offline() could not write the verified file; activating the
+        # same machine again is free.
+        "file_write_failed",
     }
 )
 _SERVER_ERROR_CODE_RE = re.compile(r"[a-z][a-z0-9_]{0,63}")
@@ -577,6 +621,100 @@ def is_transient_error(error: Union[str, BaseException, None]) -> bool:
     return code not in DEFINITIVE_ERROR_CODES
 
 
+# HWID v2: sha256("authforge-hwid-v2|" + app_id + "|" + machine_id), where machine_id is
+# the OS machine id (macOS IOPlatformUUID, Linux /etc/machine-id, Windows MachineGuid).
+# Every SDK derives the same value; conformance is pinned by hwid_vectors.json.
+HWID_V2_PREFIX = "authforge-hwid-v2|"
+_MACHINE_ID_COMMAND_TIMEOUT = 2
+_LINUX_MACHINE_ID_PATHS = ("/etc/machine-id", "/var/lib/dbus/machine-id")
+_MACHINE_ID_RE = re.compile(r"[0-9a-f-]+")
+_ALL_ZERO_MACHINE_ID_RE = re.compile(r"[0-]+")
+_IOREG_PLATFORM_UUID_RE = re.compile(r'"IOPlatformUUID"\s*=\s*"([^"]+)"')
+_ASCII_WS_SPLIT_RE = re.compile(r"[ \t\r\n]+")
+
+
+def hwid_from_machine_id(app_id: str, machine_id: str) -> str:
+    """Derive the HWID from an already-normalized machine id (or a ``legacy:`` fallback id)."""
+    material = f"{HWID_V2_PREFIX}{app_id}|{machine_id}"
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+def normalize_machine_id(raw: Optional[str]) -> Optional[str]:
+    """Trim and lowercase an OS machine id; ``None`` when it is not a usable id."""
+    if not isinstance(raw, str):
+        return None
+    value = raw.strip(" \t\r\n")
+    # ASCII-only lowercasing; the character check below rejects anything non-ASCII.
+    value = "".join(chr(ord(c) + 32) if "A" <= c <= "Z" else c for c in value)
+    if len(value) < 8 or len(value) > 128:
+        return None
+    if not _MACHINE_ID_RE.fullmatch(value):
+        return None
+    if _ALL_ZERO_MACHINE_ID_RE.fullmatch(value):
+        return None
+    return value
+
+
+def parse_ioreg_platform_uuid(output: Optional[str]) -> Optional[str]:
+    """Extract IOPlatformUUID from ``ioreg -rd1 -c IOPlatformExpertDevice`` output."""
+    if not isinstance(output, str):
+        return None
+    match = _IOREG_PLATFORM_UUID_RE.search(output)
+    return match.group(1) if match else None
+
+
+def parse_reg_query_machine_guid(output: Optional[str]) -> Optional[str]:
+    """Extract MachineGuid from ``reg.exe query ... /v MachineGuid`` output."""
+    if not isinstance(output, str):
+        return None
+    for line in re.split(r"\r?\n", output):
+        tokens = [t for t in _ASCII_WS_SPLIT_RE.split(line) if t]
+        if len(tokens) >= 3 and tokens[0].lower() == "machineguid" and tokens[1] == "REG_SZ":
+            return tokens[2]
+    return None
+
+
+def _read_os_machine_id() -> Optional[str]:
+    """The normalized OS machine id, or ``None``. Never raises."""
+    try:
+        if sys.platform == "darwin":
+            result = subprocess.run(
+                ["/usr/sbin/ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
+                capture_output=True,
+                text=True,
+                timeout=_MACHINE_ID_COMMAND_TIMEOUT,
+            )
+            if result.returncode != 0:
+                return None
+            return normalize_machine_id(parse_ioreg_platform_uuid(result.stdout))
+        if sys.platform.startswith("linux"):
+            for path in _LINUX_MACHINE_ID_PATHS:
+                try:
+                    with open(path, "r", encoding="utf-8", errors="replace") as handle:
+                        machine_id = normalize_machine_id(handle.read())
+                except Exception:
+                    continue  # missing or unreadable: try the next source
+                if machine_id:
+                    return machine_id
+            return None
+        if sys.platform == "win32":
+            import winreg
+
+            with winreg.OpenKey(
+                winreg.HKEY_LOCAL_MACHINE,
+                r"SOFTWARE\Microsoft\Cryptography",
+                0,
+                winreg.KEY_READ | winreg.KEY_WOW64_64KEY,
+            ) as key:
+                value, value_type = winreg.QueryValueEx(key, "MachineGuid")
+            if value_type != winreg.REG_SZ or not isinstance(value, str):
+                return None
+            return normalize_machine_id(value)
+    except Exception:
+        pass  # fall through to the legacy fingerprint
+    return None
+
+
 def _warn(message: str) -> None:
     # sys.stderr is None under pythonw, and a closed stream must not stop check-ins.
     stream = sys.stderr
@@ -769,6 +907,70 @@ class AuthForgeClient:
         self._apply_offline_license(result)
         return True
 
+    def activate_offline(self, license_key: str, path: Optional[str] = None) -> bool:
+        """Self-serve offline activation: turn a license key into a lifetime,
+        HWID-bound ``.authforge`` file with one online call
+        (``POST /auth/offline/activate``).
+
+        Needs the App Secret (unlike air-gapped builds). The server charges the
+        app owner 2 credits for a new machine; the same machine activating
+        again gets the identical file back for free. The returned file is
+        verified locally (signature, app id, this client's HWID) before
+        anything is written. When ``path`` is set the file is written there
+        atomically, creating parent directories. On success the client is
+        authenticated exactly as after :meth:`login_from_file`, and
+        ``get_offline_license()["replay"]`` tells whether the server returned
+        a file this machine already had.
+
+        Raises :class:`AuthForgeError` on any refusal: ``exc.code`` is the
+        server code, ``offline_file_rejected`` (the message carries the
+        verifier's reason), ``file_write_failed`` or a network code. Never
+        calls ``on_failure`` or ``os._exit``. On failure nothing is written to
+        ``path`` and the client is not authenticated by this call; an existing
+        session is kept. On success the session is replaced, as with
+        :meth:`login_from_file`.
+        """
+        if not license_key or not isinstance(license_key, str):
+            raise ValueError("license_key must be a non-empty string")
+        self._require_app_secret()
+        target = os.fspath(path) if path else None
+        body: Dict[str, Any] = {
+            "appId": self.app_id,
+            "appSecret": self.app_secret,
+            "licenseKey": license_key,
+            "hwid": self._hwid,
+            "nonce": self._generate_nonce(),
+        }
+        try:
+            # A network failure must raise here, never reach on_failure / os._exit.
+            response_obj = self._post_json("/auth/offline/activate", body)
+        except AuthForgeError:
+            raise
+        except Exception as exc:
+            raise AuthForgeError("network_error", f"network_error: {exc}") from exc
+        if not self._is_success_status(response_obj.get("status")):
+            raise self._heartbeat_verdict(response_obj)
+        file_text = response_obj.get("file")
+        if not isinstance(file_text, str) or not file_text:
+            raise AuthForgeError("unexpected_response", "unexpected_response: missing file")
+
+        # The verifier's reason goes in the message only: the server's
+        # hwid_mismatch means "no free seat" and must stay distinguishable.
+        result = verify_license_file(file_text, self.app_id, self.public_keys, self._hwid)
+        if not result["ok"]:
+            raise AuthForgeError(
+                "offline_file_rejected", f"offline_file_rejected: {result['error']}"
+            )
+
+        if target is not None:
+            try:
+                _write_file_atomic(target, file_text.encode("utf-8"))
+            except OSError as exc:
+                raise AuthForgeError("file_write_failed", f"file_write_failed: {exc}") from exc
+
+        self._apply_offline_license(result, replay=response_obj.get("replay") is True)
+        return True
+
     def verify_license_file(
         self,
         path_or_text: str,
@@ -798,7 +1000,9 @@ class AuthForgeClient:
         with open(path_or_text, "r", encoding="utf-8") as handle:
             return handle.read()
 
-    def _apply_offline_license(self, result: VerifyLicenseFileSuccess) -> None:
+    def _apply_offline_license(
+        self, result: VerifyLicenseFileSuccess, *, replay: Optional[bool] = None
+    ) -> None:
         # Stop any online session first so the two modes never overlap.
         self.logout()
         lic = result["license"]
@@ -830,6 +1034,10 @@ class AuthForgeClient:
                 summary["label"] = lic["label"]
             if "license_expires_at" in lic:
                 summary["license_expires_at"] = lic["license_expires_at"]
+            if replay is not None:
+                # Only set by activate_offline(): True when the server returned
+                # the file this machine already had (free).
+                summary["replay"] = replay
             self._offline_license = summary
             self._authenticated = True
 
@@ -875,7 +1083,7 @@ class AuthForgeClient:
             }
             if self.ttl_seconds is not None:
                 body["ttlSeconds"] = self.ttl_seconds
-            response_obj = self._post_json("/auth/validate", body, skip_failure_hook=True)
+            response_obj = self._post_json("/auth/validate", body)
             expected_nonce = str(body.get("nonce", "")).strip()
             parsed = self._parse_validate_success(response_obj, expected_nonce)
             result: ValidateLicenseSuccess = {
@@ -934,6 +1142,8 @@ class AuthForgeClient:
 
         resolved_session = resolved_session or current_session
 
+        # Every failure raises, a network failure as AuthForgeError
+        # network_error / timeout; self_ban never calls on_failure / os._exit.
         if resolved_session:
             body: Dict[str, Any] = {
                 "appId": self.app_id,
@@ -1066,7 +1276,7 @@ class AuthForgeClient:
             "hwid": hwid,
         }
         # Network failures surface once, as heartbeat_failed / network_error.
-        response_obj = self._post_json("/auth/heartbeat", body, skip_failure_hook=True)
+        response_obj = self._post_json("/auth/heartbeat", body)
         if not self._is_success_status(response_obj.get("status")):
             raise self._heartbeat_verdict(response_obj)
         expected_nonce = str(body.get("nonce", "")).strip()
@@ -1125,6 +1335,7 @@ class AuthForgeClient:
         }
         if self.ttl_seconds is not None:
             body["ttlSeconds"] = self.ttl_seconds
+        # Network failures surface once, as login_failed / network_error.
         response_obj = self._post_json("/auth/validate", body)
         expected_nonce = str(body.get("nonce", "")).strip()
         self._apply_signed_response(
@@ -1229,9 +1440,7 @@ class AuthForgeClient:
             self._license_variables = parsed["license_variables"]
             self._authenticated = True
 
-    def _post_json(
-        self, path: str, data: Dict[str, Any], *, skip_failure_hook: bool = False
-    ) -> Dict[str, Any]:
+    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
@@ -1271,8 +1480,6 @@ class AuthForgeClient:
                         network_attempt += 1
                         time.sleep(NETWORK_RETRY_DELAY)
                         continue
-                    if not skip_failure_hook:
-                        self._fail("network_error", exc)
                     reason = getattr(exc, "reason", exc)
                     code = "timeout" if isinstance(reason, (socket.timeout, TimeoutError)) else "network_error"
                     raise AuthForgeError(code, f"url_error: {exc}") from exc
@@ -1299,6 +1506,11 @@ class AuthForgeClient:
         return obj
 
     def _get_hwid(self) -> str:
+        machine_id = _read_os_machine_id() or "legacy:" + self._legacy_fingerprint()
+        return hwid_from_machine_id(self.app_id, machine_id)
+
+    # Pre-2.0 fingerprint, kept only as the fallback when no OS machine id is readable.
+    def _legacy_fingerprint(self) -> str:
         mac = self._safe_mac_address()
         cpu = self._safe_cpu_info()
         disk = self._safe_disk_serial()

{authforge_sdk-1.4.1 → authforge_sdk-2.0.0/authforge_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.4.1
+Version: 2.0.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -38,7 +38,7 @@ Uses `cryptography` for Ed25519 verification. Works on Python 3.9+.
 2. **Run through the grace period.** By default the app keeps running on the signed session with no further network calls. A background check re-verifies the signature locally and fails when the session TTL expires. The grace period equals the session TTL: default 24h, and the server clamps requested values to 1h to 7d.
 3. **Optionally enable online check-ins.** With `online_heartbeat=True`, the SDK also calls `POST /auth/heartbeat` every `heartbeat_interval` seconds for fast revocation and concurrent-use detection.
 
-Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge).
+Separately, for machines that can **never** reach the internet, an operator can mint a signed **offline license file (`.authforge`)** in the AuthForge dashboard or Developer API. The SDK verifies it locally with your app public key: see [Offline license files](#offline-license-files-authforge). If the machine can go online **once**, the end user can get that file themselves with `activate_offline()`: see [Self-serve offline activation](#self-serve-offline-activation).
 
 ## Features
 
@@ -50,8 +50,9 @@ Everything in this list ships in `authforge.py` today:
 - **Grace period by default**: after one successful activation, the app runs on the signed session (no network) until the TTL expires.
 - **Online check-ins** (opt-in): periodic `/auth/heartbeat` calls for fast revocation and concurrent-use detection.
 - **Offline license files (`.authforge`)**: `login_from_file()` / `verify_license_file()` verify a cloud-minted, Ed25519-signed file with zero network access for air-gapped machines.
+- **Self-serve offline activation**: `activate_offline()` turns a license key into a lifetime, HWID-bound `.authforge` file with one online call, then runs offline from that file.
 - **Nonce anti-replay**: a fresh 128-bit nonce is sent on every request and the echoed nonce in the signed payload is checked before the response is accepted.
-- **HWID fingerprinting**: deterministic device hash from MAC + CPU + disk serial, with graceful per-component fallback.
+- **HWID v2**: per-app device id derived from the OS machine id (macOS `IOPlatformUUID`, Linux `/etc/machine-id`, Windows `MachineGuid`), identical across all AuthForge SDKs for the same app and machine.
 - **`hwid_override`**: bind to any identity instead of the machine (for example `tg:<id>`, `discord:<id>`).
 - **Seat enforcement**: the server binds each HWID into a license's free slots up to `maxHwidSlots`; `hwid_count` / `max_hwid_slots` are surfaced on the result. A shared (unlimited-seat) key skips per-device binding.
 - **Self-ban** (`self_ban()`) for anti-tamper response, both pre-session and post-session.
@@ -118,7 +119,7 @@ client = AuthForgeClient(
 | `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) | The grace period duration: how long the app keeps running on the signed session without contacting AuthForge. Server clamps to `[3600, 604800]` (1h to 7d); preserved across check-in 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. |
+| `hwid_override` | `str \| None` | `None` | Optional custom hardware/subject identifier. When set to a non-empty value, the SDK uses it instead of deriving the HWID from the OS machine id. |
 | `online_heartbeat` | bool (keyword-only) | `False` | Enable online check-ins: periodic `POST /auth/heartbeat` for fast revocation and concurrent-use detection. |
 
 ### Identity-based binding example (Telegram/Discord)
@@ -189,12 +190,81 @@ if client.login_from_file("license.authforge"):
     print(client.get_license_variables())
 ```
 
-Collect the HWID from the same SDK build that will load the file: fingerprints are not portable across SDKs or languages. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
+Since 2.0 every AuthForge SDK computes the same HWID for the same app id and machine, but HWIDs collected before upgrading to 2.0 no longer match: collect the HWID again after upgrading. After `login_from_file()`, `get_session_kind()` returns `"offline"` (`"online"` after `login()`, `None` when logged out).
 
 `verify_license_file()` (module function and client method) performs the same checks without touching client state. Failure codes, in check order: `bad_armor`, `bad_signature`, `unsupported_version`, `malformed_payload`, `wrong_app`, `expired`, `hwid_mismatch`. `login_from_file()` reports them through `on_failure("offline_login_failed", exc)` and returns `False`; it never calls `os._exit`.
 
 File format (version 1): PEM-style armor with informational headers, a base64 JSON payload (`v`, `appId`, `licenseKey`, `jti`, `kid`, `issuedAt`, `expiresAt`, `hwid` policy, optional label/variable snapshots) and a detached Ed25519 signature over the UTF-8 bytes of the base64 payload string - the same contract as `/auth/validate`. See `offline_license_vectors.json` for conformance vectors.
 
+## Self-serve offline activation
+
+A separate mode for apps that sell a one-time license and then run with no network: the end user types the license key once, `activate_offline()` makes **one** online call (`POST /auth/offline/activate`) and gets back a lifetime `.authforge` file bound to this machine's HWID. From then on the app starts with `login_from_file()` and never contacts AuthForge again.
+
+How it differs from air-gapped offline files:
+
+- It **needs the App Secret**, because it is an online call. Air-gapped builds that only use `login_from_file()` still ship with `app_secret=None`.
+- The app owner opts the app in (app settings in the dashboard). Only **perpetual**, **seat-limited** licenses can self-serve; each license can produce files for at most `maxHwidSlots` distinct machines, ever. HWID resets do not free those machine slots.
+- **Billing:** a new machine costs the app owner **2 credits**, once. The same machine activating again (reinstall, deleted file) gets the identical file back for **free**. A refused activation costs nothing.
+- **A refund or chargeback revokes the license online but cannot reach files already issued.** A lifetime file keeps working on its machine.
+
+```python
+import os
+import sys
+
+from authforge import AuthForgeClient, AuthForgeError
+
+LICENSE_PATH = os.path.join(os.path.expanduser("~"), ".myapp", "license.authforge")
+
+client = AuthForgeClient(
+    app_id="YOUR_APP_ID",
+    app_secret="YOUR_APP_SECRET",  # required for activate_offline (online call)
+    public_key="YOUR_PUBLIC_KEY",
+    on_failure=lambda reason, exc: None,  # login_from_file reports why it failed here
+)
+
+# 1. No network, no credits: run from the file if it is there and valid.
+if not (os.path.exists(LICENSE_PATH) and client.login_from_file(LICENSE_PATH)):
+    # 2. No file yet, or it fails (e.g. hwid_mismatch after a hardware change).
+    key = input("License key: ").strip()
+    try:
+        client.activate_offline(key, path=LICENSE_PATH)
+    except AuthForgeError as exc:
+        if exc.code == "offline_activation_limit_reached":
+            print("This license is active on its maximum number of machines. Please contact the vendor.")
+        elif exc.code in {"invalid_key", "revoked", "expired"}:
+            print("That license key is not valid.")
+        elif exc.code == "hwid_mismatch":
+            print("No free seat on this license for this machine.")
+        elif exc.transient:
+            print(f"Could not activate right now ({exc.code}). Check your connection and try again.")
+        else:
+            print(f"Activation failed: {exc.code}")
+        sys.exit(1)
+
+print("Licensed:", client.get_license_variables())
+```
+
+`activate_offline(license_key, path=None)` returns `True` on success and raises `AuthForgeError` otherwise. It:
+
+1. Fails fast with the usual "app_secret is required" `ValueError` (no request) when the client has no App Secret.
+2. Sends `appId`, `appSecret`, `licenseKey`, the same HWID `login()` sends and a fresh nonce, with the same retries as `login()` (`rate_limited` after 2s then 5s, one retry on a network error).
+3. Verifies the returned file with your public key(s), app id and this machine's HWID **before** writing anything. A file that fails raises `offline_file_rejected`; the message includes the verifier's reason (`bad_signature`, `wrong_app`, `hwid_mismatch`, ...).
+4. If `path` is set, writes the file byte-for-byte and atomically (temp file in the same directory, then rename), creating parent directories.
+5. Leaves the client authenticated exactly as `login_from_file()` does: `get_session_kind()` is `"offline"`, variables and `get_offline_license()` are set, no background checks start. `get_offline_license()["replay"]` is `True` when the server returned a file this machine already had.
+
+On any failure nothing is written to `path` (an existing file there is left as it was), the call does not authenticate the client (an existing session is kept), and neither `on_failure` nor `os._exit` is called.
+
+| Code | Kind | Meaning |
+| --- | --- | --- |
+| `offline_activation_disabled` | fatal | The app has not opted in to self-serve activation |
+| `offline_activation_requires_perpetual` | fatal | The license has an expiry; only perpetual licenses can self-serve |
+| `offline_activation_requires_seats` | fatal | Unlimited-seat (shared) licenses cannot self-serve |
+| `offline_activation_limit_reached` | fatal | Every machine slot on the license is used; the buyer must contact the vendor |
+| `offline_file_rejected` | fatal | SDK code: the returned file failed local verification; nothing was written |
+| `hwid_mismatch` | fatal | No free seat on the license for this machine (server code, not the verifier's) |
+| `file_write_failed` | transient | The verified file could not be written to `path`; activating again is free |
+| `invalid_key`, `revoked`, `expired`, `no_credits`, `rate_limited`, `unexpected_response`, `network_error`, ... | as everywhere else | Existing codes keep their meaning and classification |
+
 ## Migrating from heartbeat_mode
 
 Earlier releases required `heartbeat_mode="LOCAL"` or `"SERVER"`. The argument is now optional and deprecated; it still works but emits a `DeprecationWarning`.
@@ -217,6 +287,7 @@ For code that still reads it, `client.heartbeat_mode` remains available and refl
 
 - **1 `login()` or `validate_license()` call = 1 credit** (one `/auth/validate` debit each).
 - **10 online check-ins on the same license = 1 credit** (billed every 10th successful `/auth/heartbeat`). Grace period checks are local and free.
+- **1 new offline activation (`activate_offline()`) = 2 credits**, charged to the app owner; re-activating the same machine is free. `login_from_file()` is always free.
 
 A desktop app running 6h/day with online check-ins at a 15-minute interval burns ~3-4 credits/day. The server enforces `/auth/heartbeat` at 6 requests/minute per license key, so keep intervals at 10 seconds or higher and pick the interval based on how fast you need revocations to propagate (they always land on the **next** check-in).
 
@@ -226,8 +297,9 @@ A desktop app running 6h/day with online check-ins at a 15-minute interval burns
 |---|---|---|
 | `login(license_key)` | `bool` | Activates: validates the key online and stores the signed session (`sessionToken`, `expiresIn`, `appVariables`, `licenseVariables`) |
 | `validate_license(license_key)` | `ValidateLicenseResult` | Same `/auth/validate` + signatures as `login`; does not store session or start background checks; 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) |
+| `self_ban(...)` | `dict` | Requests `/auth/selfban` to blacklist HWID/IP and optionally revoke (session-authenticated only). Raises `ValueError` on any failure (a network failure as `AuthForgeError` `network_error` / `timeout`); never calls `on_failure` or `os._exit` |
 | `login_from_file(path_or_text)` | `bool` | Authorizes from an offline `.authforge` file with no network; never starts background checks; failures go to `on_failure("offline_login_failed", …)` |
+| `activate_offline(license_key, path=None)` | `bool` | Self-serve offline activation: one online call returns a lifetime HWID-bound `.authforge` file, verified locally, written atomically to `path` and applied like `login_from_file`. Needs the App Secret; raises `AuthForgeError` on refusal; never calls `on_failure` or `os._exit` |
 | `verify_license_file(path_or_text, *, now=None)` | `VerifyLicenseFileResult` | Verifies a `.authforge` file with this client's app id / keys / HWID without changing state |
 | `get_offline_license()` | `dict \| None` | Metadata of the offline file in use (`jti`, `expires_at`, `hwid_policy`, …) |
 | `get_session_kind()` | `"online" \| "offline" \| None` | Which kind of session the client holds (`None` when logged out) |
@@ -247,7 +319,11 @@ If authentication fails (activation rejected, check-in fails, signature mismatch
 **`validate_license()`** does not trigger `on_failure` or `os._exit`: check `result["valid"]` and `result["code"]`.
 
 Recognized server errors (`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`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`. Codes added to the server later are passed through unchanged.
+`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `app_burn_cap_reached`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`, `malformed_request`, `demo_quota_exceeded`, `system_error`, and from `activate_offline()`: `offline_activation_disabled`, `offline_activation_requires_perpetual`, `offline_activation_requires_seats`, `offline_activation_limit_reached`, plus the SDK code `offline_file_rejected`. Codes added to the server later are passed through unchanged.
+
+**`activate_offline()`** does not trigger `on_failure` or `os._exit` either: it raises `AuthForgeError` (see [Self-serve offline activation](#self-serve-offline-activation)).
+
+**`self_ban()`** does not trigger `on_failure` or `os._exit` either: every failure raises, a server rejection as `ValueError(code)` and a network failure as `AuthForgeError` with `exc.code` `network_error` or `timeout`.
 
 Request retries are automatic inside the internal HTTP layer:
 - `rate_limited`, or HTTP 429 with no error code: retry after 2s, then 5s (max 3 attempts total)
@@ -266,10 +342,10 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 
 | Kind | Codes | What the SDK does |
 |---|---|---|
-| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
+| Fatal | `revoked`, `expired`, `hwid_mismatch` (the HWID is no longer bound to the license, for example after an HWID reset), `blocked` (HWID/IP blacklisted or not whitelisted), `session_expired` (also raised locally when the grace period or session TTL runs out), `malformed_request`, `app_disabled`, `invalid_app`, `signature_mismatch` (plus the `activate_offline()`-only codes `offline_activation_*` and `offline_file_rejected`) | Clears the stored session (as `logout()` does) and stops background checks **before** calling `on_failure`, so the grace period cannot keep the app running on it. `on_failure` may call `login()` again. |
 | Transient | Everything else: `network_error`, `timeout`, `rate_limited`, `system_error`, `no_credits`, `demo_quota_exceeded`, `app_burn_cap_reached`, `bad_request`, `invalid_key`, every `http_error_<status>`, `invalid_json_response`, `unexpected_response`, `nonce_mismatch`, any unrecognized code | Keeps the session and checks in again on the next `heartbeat_interval`. Once the signed session's TTL has passed, the next transient failure is reported as a fatal `session_expired` instead. |
 
-Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Heartbeat network failures are reported once, as `heartbeat_failed` with code `network_error` or `timeout`, not as a separate `network_error` reason.
+Transient failures only keep checking in if `on_failure` returns normally. Without a callback, a transient failure prints `AuthForge: background check failed (<code>); retrying next interval` to stderr and check-ins continue; a fatal one, including the `session_expired` a transient failure becomes once the session TTL has passed, still ends the process with `os._exit(1)`. Network failures are reported once, with code `network_error` or `timeout`: as `heartbeat_failed` from check-ins and as `login_failed` from `login()`, never as a separate `network_error` reason. `activate_offline()` and `self_ban()` raise them as `AuthForgeError` instead.
 
 `on_failure` runs on the background heartbeat thread with no SDK lock held, so calling `logout()`, `is_authenticated()` or `login()` from it is safe. A check-in that is still in flight when you call `logout()` or `login()` is discarded: it cannot restore the old session or report a failure for it.
 
@@ -339,11 +415,12 @@ client.self_ban(
 - 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.
+- Every failure raises: a server rejection as `ValueError(code)`, a network failure (after one retry) as `AuthForgeError` with `exc.code` `network_error` or `timeout`. `self_ban()` never calls `on_failure` or `os._exit`, with or without a callback.
 - Not available after `login_from_file()`: offline sessions have no server session, so `self_ban()` with no explicit `license_key` / `session_token` raises `ValueError("offline_session")` without contacting the server.
 
 ## How It Works
 
-1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
+1. **Activate**: `login()` uses `hwid_override` if provided; otherwise it derives the HWID from the OS machine id (see [Hardware ID](#hardware-id)). 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 with a TTL. The SDK verifies the Ed25519 signature and nonce to prevent replay attacks.
 
 2. **Background checks**: a daemon thread wakes at the configured interval. By default it enforces the grace period: it re-verifies the stored signature and checks expiry without network calls. With `online_heartbeat=True`, it instead sends `/auth/heartbeat` with a fresh nonce and verifies the response.
 
@@ -351,18 +428,29 @@ client.self_ban(
 
 ## Hardware ID
 
-The SDK generates a deterministic hardware fingerprint by hashing:
-- MAC address
-- CPU identifier
-- Disk serial number
+The HWID (v2, since 2.0) is
+
+`SHA256("authforge-hwid-v2|" + app_id + "|" + machine_id)` as lowercase hex,
+
+where `machine_id` is the operating system's own machine id, trimmed and lowercased:
+
+| OS | Source |
+| -- | ------ |
+| macOS | `IOPlatformUUID` (`/usr/sbin/ioreg -rd1 -c IOPlatformExpertDevice`) |
+| Linux | `/etc/machine-id`, then `/var/lib/dbus/machine-id` |
+| Windows | `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` (64-bit registry view, via `winreg`) |
+
+These ids survive network changes, renames, disk usage and USB devices. Including the app id means two different apps on the same machine get unrelated HWIDs. Every AuthForge SDK computes the same value for the same app id and machine; `hwid_vectors.json` pins this. The HWID is sent with every auth request so the server can enforce per-device license limits.
+
+If no valid OS id can be read (for example a container without `/etc/machine-id`), the SDK falls back to `legacy:<the pre-2.0 fingerprint of MAC, CPU and disk serial>` as the machine id. Containers built from one image can also share a baked-in machine id, so for containers prefer `hwid_override` with an identifier you control.
 
-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.
+The helpers `hwid_from_machine_id`, `normalize_machine_id`, `parse_ioreg_platform_uuid` and `parse_reg_query_machine_guid` are exported for tooling and tests.
 
 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. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects.
+The shared `test_vectors.json` file validates cross-language Ed25519 verification behavior. `offline_license_vectors.json` (generated from a fixed test seed in the Node SDK repo) is the cross-SDK conformance suite for `.authforge` offline license files: good files plus the `bad_signature`, wrong key, `wrong_app`, `expired`, `hwid_mismatch`, `unsupported_version` and `bad_armor` rejects. `self_serve_activation_vectors.json` is the cross-SDK suite for `activate_offline()`: mocked `/auth/offline/activate` responses with the expected written file, session and error code. `hwid_vectors.json` (generated by `authforge-node/generate_hwid_vectors.mjs`) is the cross-SDK suite for HWID v2: derivation, machine id normalization, and the `ioreg` / `reg query` parsers.
 
 ## Requirements
 

{authforge_sdk-1.4.1 → authforge_sdk-2.0.0}/pyproject.toml

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