Add createActivationRequest so air-gapped customers can send a checksummed HWID file.

Author: RAZKOM

AGENTS.md

@@ -7,7 +7,7 @@
 
 AuthForge is a license key validation service. Your app activates by sending a license key + hardware ID to `POST /auth/validate`; the server checks revocation, expiry, HWID binding, and credits, then returns an Ed25519-signed session with a TTL. By default the app then runs through the **grace period**: it keeps running on the signed session with no network calls, and a background check fails when the session TTL expires. Optionally, enable **online check-ins** (`online_heartbeat=True`): periodic `POST /auth/heartbeat` calls for fast revocation and concurrent-use detection. If the license is revoked or expired, the check-in fails and you handle it (typically exit the app).
 
-There is also a **separate** mode for machines that can never reach the internet: **offline license files (`.authforge`)**. The operator mints a signed file in the AuthForge cloud; `login_from_file()` verifies it locally with the app public key and the machine HWID, with zero network calls. Do not ship the App Secret in those builds (`app_secret=None`). Only use it when the user explicitly asks for air-gapped / offline-file licensing. The default integration is always online `login()` + grace period.
+There is also a **separate** mode for machines that can never reach the internet: **offline license files (`.authforge`)**. The operator mints a signed file in the AuthForge cloud; `login_from_file()` verifies it locally with the app public key and the machine HWID, with zero network calls. Do not ship the App Secret in those builds (`app_secret=None`). Only use it when the user explicitly asks for air-gapped / offline-file licensing. The default integration is always online `login()` + grace period. To collect the HWID for a bound file, write an **activation request** (`.authforge-request`) with `create_activation_request` / `write_activation_request`. It is not a license, is not signed, and does not mint anything. Prefer it over printing the raw HWID.
 
 ## Billing model (so you can pick sensible intervals)
 
@@ -97,6 +97,8 @@ The attribute `client.heartbeat_mode` still exists for back-compat and reflects
 | `get_offline_license()` | `dict \| None` | `jti`, `expires_at`, `hwid_policy`, … of the offline file in use |
 | `get_session_kind()` | `"online" \| "offline" \| None` | Kind of session the client holds; `None` when logged out |
 | `get_hwid()` | `str` | HWID this client sends; the customer reports it so the operator can mint a bound file |
+| `create_activation_request(**kwargs)` | `str` | Unsigned `.authforge-request` for this machine. No network, no secret, callable before `login()`. Hostname omitted unless `include_machine_name=True` |
+| `write_activation_request(path, **kwargs)` | `None` | Writes that file as UTF-8 |
 | `logout()` | `None` | Stops background checks and clears session state |
 | `is_authenticated()` | `bool` | Whether a session token is present and marked authenticated |
 | `get_session_data()` | `dict \| None` | Decoded signed payload map |

README.md

@@ -151,8 +151,8 @@ client = AuthForgeClient(
     on_failure=lambda reason, exc: print(reason, exc),
 )
 
-# 1. The customer sends you this value so you can bind the file to their machine:
-print("HWID:", client.get_hwid())
+# 1. Write an activation request the operator drops into the mint dialog:
+client.write_activation_request("machine.authforge-request")
 
 # 2. Later, authorize from the minted file (path or armored text). No network.
 if client.login_from_file("license.authforge"):
@@ -204,6 +204,8 @@ A desktop app running 6h/day with online check-ins at a 15-minute interval burns
 | `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) |
 | `get_hwid()` | `str` | The HWID this client sends (or `hwid_override`); customers share it to receive a bound file |
+| `create_activation_request(**kwargs)` | `str` | Unsigned `.authforge-request` for this machine. No network, no secret. Hostname omitted unless `include_machine_name=True` |
+| `write_activation_request(path, **kwargs)` | `None` | Writes that file as UTF-8 |
 | `logout()` | `None` | Stops background checks and clears all session/auth state |
 | `is_authenticated()` | `bool` | True when an active authenticated session exists |
 | `get_session_data()` | `dict \| None` | Full decoded payload map |

activation_request_vectors.json

@@ -0,0 +1,51 @@
+{
+  "format": "authforge-activation-request",
+  "version": 1,
+  "description": "Cross-SDK conformance vectors for activation requests (.authforge-request). Generators with the same inputs must match good_minimal and good_full byte-for-byte. Parser tolerance: CRLF, UTF-8 BOM, re-wrapping, email preamble. Checksum is decision-relevant.",
+  "cases": [
+    {
+      "name": "good_minimal",
+      "expect": "ok",
+      "inputs": {
+        "appId": "test-app",
+        "hwid": "testhwid",
+        "createdAt": "2026-09-11T12:00:00.000Z"
+      },
+      "file": "-----BEGIN AUTHFORGE ACTIVATION REQUEST-----\nVersion: 1\nApp-Id: test-app\nChecksum: c64d10a2fe4d54f7\n\neyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtYWN0aXZhdGlvbi1yZXF1ZXN0IiwiYXBw\nSWQiOiJ0ZXN0LWFwcCIsImh3aWQiOiJ0ZXN0aHdpZCIsImNyZWF0ZWRBdCI6IjIw\nMjYtMDktMTFUMTI6MDA6MDAuMDAwWiJ9\n-----END AUTHFORGE ACTIVATION REQUEST-----\n"
+    },
+    {
+      "name": "good_full",
+      "expect": "ok",
+      "inputs": {
+        "appId": "test-app",
+        "hwid": "testhwid",
+        "createdAt": "2026-09-11T12:00:00.000Z",
+        "machineName": "dev-box",
+        "os": "Windows 11",
+        "sdk": "python/1.2.1",
+        "licenseKey": "TEST-KEY0-0000-0000"
+      },
+      "file": "-----BEGIN AUTHFORGE ACTIVATION REQUEST-----\nVersion: 1\nApp-Id: test-app\nChecksum: e496a94a849114c3\n\neyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtYWN0aXZhdGlvbi1yZXF1ZXN0IiwiYXBw\nSWQiOiJ0ZXN0LWFwcCIsImh3aWQiOiJ0ZXN0aHdpZCIsImNyZWF0ZWRBdCI6IjIw\nMjYtMDktMTFUMTI6MDA6MDAuMDAwWiIsIm1hY2hpbmVOYW1lIjoiZGV2LWJveCIs\nIm9zIjoiV2luZG93cyAxMSIsInNkayI6InB5dGhvbi8xLjIuMSIsImxpY2Vuc2VL\nZXkiOiJURVNULUtFWTAtMDAwMC0wMDAwIn0=\n-----END AUTHFORGE ACTIVATION REQUEST-----\n"
+    },
+    {
+      "name": "tolerate_crlf_bom_preamble",
+      "expect": "ok",
+      "file": "Please see attached.\r\n-----BEGIN AUTHFORGE ACTIVATION REQUEST-----\r\nVersion: 1\r\nApp-Id: test-app\r\nChecksum: c64d10a2fe4d54f7\r\n\r\neyJ2IjoxLCJ0eXAiOiJh\r\ndXRoZm9yZ2UtYWN0aXZh\r\ndGlvbi1yZXF1ZXN0Iiwi\r\nYXBwSWQiOiJ0ZXN0LWFw\r\ncCIsImh3aWQiOiJ0ZXN0\r\naHdpZCIsImNyZWF0ZWRB\r\ndCI6IjIwMjYtMDktMTFU\r\nMTI6MDA6MDAuMDAwWiJ9\r\n-----END AUTHFORGE ACTIVATION REQUEST-----\r\nThanks,\r\nPat\r\n"
+    },
+    {
+      "name": "bad_checksum",
+      "expect": "checksum_mismatch",
+      "file": "-----BEGIN AUTHFORGE ACTIVATION REQUEST-----\nVersion: 1\nApp-Id: test-app\nChecksum: deadbeefdeadbeef\n\neyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtYWN0aXZhdGlvbi1yZXF1ZXN0IiwiYXBw\nSWQiOiJ0ZXN0LWFwcCIsImh3aWQiOiJ0ZXN0aHdpZCIsImNyZWF0ZWRBdCI6IjIw\nMjYtMDktMTFUMTI6MDA6MDAuMDAwWiJ9\n-----END AUTHFORGE ACTIVATION REQUEST-----\n"
+    },
+    {
+      "name": "truncated_body",
+      "expect": "reject",
+      "file": "-----BEGIN AUTHFORGE ACTIVATION REQUEST-----\nVersion: 1\nApp-Id: test-app\nChecksum: c64d10a2fe4d54f7\n\neyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtYWN0aXZhdGlvbi1yZXF1ZXN0IiwiYXBw\nSWQiOiJ0ZXN0LWFwcCIsImh3aWQiOiJ0ZXN0aHdpZCIsImNyZWF0ZWRBdCI6IjIw\nMjYtMDktMTFUMTI6MDA6\n-----END AUTHFORGE ACTIVATION REQUEST-----\n"
+    },
+    {
+      "name": "license_file",
+      "expect": "is_license_file",
+      "file": "-----BEGIN AUTHFORGE LICENSE-----\nVersion: 1\nApp-Id: test-app\n\nQUJD\n-----END AUTHFORGE LICENSE-----\n"
+    }
+  ]
+}

authforge.py

@@ -80,6 +80,21 @@ class ValidateLicenseFailure(TypedDict):
     "hwid_mismatch",
 )
 
+# Activation requests (`.authforge-request`): unsigned transport for a HWID.
+# Distinct markers from BEGIN AUTHFORGE LICENSE. Not signed; the Checksum
+# header is the only integrity check. Keep _SDK_TAG in sync with pyproject.toml.
+_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.2.1"
+_ARMOR_LINE_WIDTH = 64
+_MAX_REQUEST_HWID = 256
+_MAX_REQUEST_MACHINE_NAME = 128
+_MAX_REQUEST_OS = 64
+_MAX_REQUEST_SDK = 64
+_MAX_REQUEST_LICENSE_KEY = 64
+
 
 class OfflineLicense(TypedDict):
     app_id: str
@@ -117,6 +132,131 @@ class ParsedLicenseFile(TypedDict):
     signature_base64: str
 
 
+def _clip_request_field(value: str, max_len: int) -> str:
+    return value if len(value) <= max_len else value[:max_len]
+
+
+def _json_escape_request(value: str) -> str:
+    out: List[str] = []
+    for ch in value:
+        code = ord(ch)
+        if ch == "\\":
+            out.append("\\\\")
+        elif ch == '"':
+            out.append('\\"')
+        elif ch == "\b":
+            out.append("\\b")
+        elif ch == "\f":
+            out.append("\\f")
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\r":
+            out.append("\\r")
+        elif ch == "\t":
+            out.append("\\t")
+        elif code < 0x20:
+            out.append(f"\\u00{code:02x}")
+        else:
+            out.append(ch)
+    return '"' + "".join(out) + '"'
+
+
+def _wrap_armor_64(value: str) -> str:
+    return "\n".join(value[i : i + _ARMOR_LINE_WIDTH] for i in range(0, len(value), _ARMOR_LINE_WIDTH))
+
+
+def _canonical_activation_request_json(
+    *,
+    app_id: str,
+    hwid: str,
+    created_at: str,
+    machine_name: Optional[str] = None,
+    os_name: Optional[str] = None,
+    sdk: Optional[str] = None,
+    license_key: Optional[str] = None,
+) -> str:
+    parts = [
+        f'"v":{_ACTIVATION_REQUEST_VERSION}',
+        f'"typ":{_json_escape_request(_ACTIVATION_REQUEST_TYP)}',
+        f'"appId":{_json_escape_request(app_id)}',
+        f'"hwid":{_json_escape_request(_clip_request_field(hwid, _MAX_REQUEST_HWID))}',
+        f'"createdAt":{_json_escape_request(created_at)}',
+    ]
+    if machine_name:
+        parts.append(
+            f'"machineName":{_json_escape_request(_clip_request_field(machine_name, _MAX_REQUEST_MACHINE_NAME))}'
+        )
+    if os_name:
+        parts.append(f'"os":{_json_escape_request(_clip_request_field(os_name, _MAX_REQUEST_OS))}')
+    if sdk:
+        parts.append(f'"sdk":{_json_escape_request(_clip_request_field(sdk, _MAX_REQUEST_SDK))}')
+    if license_key:
+        parts.append(
+            f'"licenseKey":{_json_escape_request(_clip_request_field(license_key, _MAX_REQUEST_LICENSE_KEY))}'
+        )
+    return "{" + ",".join(parts) + "}"
+
+
+def _utc_iso_ms(value: Optional[datetime] = None) -> str:
+    now = value or datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    now = now.astimezone(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{int(now.microsecond / 1000):03d}Z"
+
+
+def _detect_os_label() -> str:
+    system = platform.system()
+    release = platform.release()
+    if system == "Darwin":
+        mac = platform.mac_ver()[0]
+        label = f"macOS {mac or release}"
+    elif system == "Windows":
+        label = f"Windows {release}"
+    elif system == "Linux":
+        label = f"Linux {release}"
+    else:
+        label = f"{system} {release}".strip()
+    return _clip_request_field(label, _MAX_REQUEST_OS)
+
+
+def format_activation_request(
+    *,
+    app_id: str,
+    hwid: str,
+    created_at: str,
+    machine_name: Optional[str] = None,
+    os: Optional[str] = None,
+    sdk: Optional[str] = None,
+    license_key: Optional[str] = None,
+) -> str:
+    """Armored ``.authforge-request`` text from explicit fields."""
+    json_body = _canonical_activation_request_json(
+        app_id=app_id,
+        hwid=hwid,
+        created_at=created_at,
+        machine_name=machine_name,
+        os_name=os,
+        sdk=sdk,
+        license_key=license_key,
+    )
+    payload_b64 = base64.b64encode(json_body.encode("utf-8")).decode("ascii")
+    checksum = hashlib.sha256(payload_b64.encode("utf-8")).hexdigest()[:16]
+    clean_app = app_id.replace("\r", " ").replace("\n", " ").strip()
+    return "\n".join(
+        [
+            _BEGIN_ACTIVATION_REQUEST,
+            f"Version: {_ACTIVATION_REQUEST_VERSION}",
+            f"App-Id: {clean_app}",
+            f"Checksum: {checksum}",
+            "",
+            _wrap_armor_64(payload_b64),
+            _END_ACTIVATION_REQUEST,
+            "",
+        ]
+    )
+
+
 def parse_license_file(text: str) -> Optional[ParsedLicenseFile]:
     """Parse armored ``.authforge`` text.
 
@@ -463,6 +603,49 @@ def get_hwid(self) -> str:
         """
         return self._hwid
 
+    def create_activation_request(
+        self,
+        *,
+        include_machine_name: bool = False,
+        machine_name: Optional[str] = None,
+        os: Optional[str] = None,
+        omit_os: bool = False,
+        sdk: Optional[str] = None,
+        omit_sdk: bool = False,
+        license_key: Optional[str] = None,
+        created_at: Optional[str] = None,
+    ) -> str:
+        """Build an activation request (``.authforge-request``) for this machine.
+
+        No network, no session, no app secret. The HWID is the same value
+        :meth:`login` / :meth:`login_from_file` use. ``machine_name`` is omitted
+        unless ``include_machine_name`` is true (hostnames are often a person's
+        name).
+        """
+        created = created_at if created_at else _utc_iso_ms()
+        name: Optional[str] = None
+        if include_machine_name:
+            name = machine_name or platform.node() or socket.gethostname()
+        os_name: Optional[str] = None if omit_os else (os if os is not None else _detect_os_label())
+        sdk_tag: Optional[str] = None if omit_sdk else (sdk if sdk is not None else _SDK_TAG)
+        key = license_key if license_key is not None else self._license_key
+        return format_activation_request(
+            app_id=self.app_id,
+            hwid=self._hwid,
+            created_at=created,
+            machine_name=name,
+            os=os_name,
+            sdk=sdk_tag,
+            license_key=key,
+        )
+
+    def write_activation_request(self, path: str, **kwargs: Any) -> None:
+        """Write an activation request to ``path`` (UTF-8). Same kwargs as
+        :meth:`create_activation_request`."""
+        text = self.create_activation_request(**kwargs)
+        with open(path, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+
     def login_from_file(self, path_or_text: str) -> bool:
         """Authorize from a cloud-minted offline license file (``.authforge``)
         with NO network access. Accepts a filesystem path or the armored text.

pyproject.toml

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