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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.5.0
+Version: 2.0.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -52,7 +52,7 @@ Everything in this list ships in `authforge.py` today:
 - **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.
@@ -119,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)
@@ -190,7 +190,7 @@ 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`.
 
@@ -297,7 +297,7 @@ 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 |
@@ -323,6 +323,8 @@ Recognized server errors (`KNOWN_SERVER_ERRORS`):
 
 **`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)
 - `no_credits`, `demo_quota_exceeded` and `app_burn_cap_reached` also arrive as HTTP 429 but are never retried immediately; online check-ins try again at the next interval
@@ -343,7 +345,7 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 | 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.
 
@@ -413,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.
 
@@ -425,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. `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.
+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.5.0 → authforge_sdk-2.0.0}/README.md

@@ -24,7 +24,7 @@ Everything in this list ships in `authforge.py` today:
 - **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.
@@ -91,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)
@@ -162,7 +162,7 @@ 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`.
 
@@ -269,7 +269,7 @@ 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 |
@@ -295,6 +295,8 @@ Recognized server errors (`KNOWN_SERVER_ERRORS`):
 
 **`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)
 - `no_credits`, `demo_quota_exceeded` and `app_burn_cap_reached` also arrive as HTTP 429 but are never retried immediately; online check-ins try again at the next interval
@@ -315,7 +317,7 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 | 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.
 
@@ -385,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.
 
@@ -397,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. `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.
+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.5.0 → 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.5.0"
+_SDK_TAG = "python/2.0.0"
 _ARMOR_LINE_WIDTH = 64
 _MAX_REQUEST_HWID = 256
 _MAX_REQUEST_MACHINE_NAME = 128
@@ -621,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
@@ -848,9 +942,8 @@ class AuthForgeClient:
             "nonce": self._generate_nonce(),
         }
         try:
-            # skip_failure_hook: a network failure must raise here, never
-            # reach on_failure / os._exit.
-            response_obj = self._post_json("/auth/offline/activate", body, skip_failure_hook=True)
+            # 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:
@@ -990,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 = {
@@ -1049,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,
@@ -1181,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()
@@ -1240,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(
@@ -1344,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
@@ -1386,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
@@ -1414,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.5.0 → authforge_sdk-2.0.0/authforge_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.5.0
+Version: 2.0.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -52,7 +52,7 @@ Everything in this list ships in `authforge.py` today:
 - **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.
@@ -119,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)
@@ -190,7 +190,7 @@ 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`.
 
@@ -297,7 +297,7 @@ 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 |
@@ -323,6 +323,8 @@ Recognized server errors (`KNOWN_SERVER_ERRORS`):
 
 **`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)
 - `no_credits`, `demo_quota_exceeded` and `app_burn_cap_reached` also arrive as HTTP 429 but are never retried immediately; online check-ins try again at the next interval
@@ -343,7 +345,7 @@ A failed check-in only counts as an AuthForge verdict when the body is a JSON ob
 | 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.
 
@@ -413,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.
 
@@ -425,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. `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.
+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.5.0 → authforge_sdk-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "authforge-sdk"
-version = "1.5.0"
+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"