authforge-sdk 1.2.0__tar.gz → 1.3.0__tar.gz

{authforge_sdk-1.2.0/authforge_sdk.egg-info → authforge_sdk-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.2.0
+Version: 1.3.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -110,7 +110,7 @@ client = AuthForgeClient(
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `app_id` | str | required | Your application ID from the AuthForge dashboard |
-| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `app_secret` | str | required for online APIs; `None` / `""` for `login_from_file` only | Your application secret from the AuthForge dashboard. Do not ship it in air-gapped binaries. |
 | `public_key` | `str \| Sequence[str]` | required | App Ed25519 public key(s) (base64) from dashboard. Pass one key, a list of keys, or a comma-separated string to trust multiple keys during rotation (see [Key rotation](#key-rotation)). |
 | `heartbeat_mode` | `str \| None` | `None` | Deprecated shim (see [Migrating from heartbeat_mode](#migrating-from-heartbeat_mode)). Use `online_heartbeat` instead. |
 | `heartbeat_interval` | int | `900` | Seconds between background checks (minimum `10`; default 15 min). Applies to both grace period checks and online check-ins. |
@@ -159,7 +159,7 @@ Tune `ttl_seconds` to set the grace period duration (server default 24h, clamped
 
 ## Offline license files (`.authforge`)
 
-For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins.
+For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins. Pass `app_secret=None` (or `""`) so the air-gapped binary does not contain the App Secret.
 
 | | Grace period (default) | Offline license file |
 | --- | --- | --- |
@@ -174,13 +174,13 @@ from authforge import AuthForgeClient
 
 client = AuthForgeClient(
     app_id="YOUR_APP_ID",
-    app_secret="YOUR_APP_SECRET",  # unused for offline files but still required by the constructor
+    app_secret=None,  # login_from_file does not use the App Secret; do not ship it in air-gapped builds
     public_key="YOUR_PUBLIC_KEY",
     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"):
@@ -232,6 +232,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 |

{authforge_sdk-1.2.0 → authforge_sdk-1.3.0}/README.md

@@ -82,7 +82,7 @@ client = AuthForgeClient(
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `app_id` | str | required | Your application ID from the AuthForge dashboard |
-| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `app_secret` | str | required for online APIs; `None` / `""` for `login_from_file` only | Your application secret from the AuthForge dashboard. Do not ship it in air-gapped binaries. |
 | `public_key` | `str \| Sequence[str]` | required | App Ed25519 public key(s) (base64) from dashboard. Pass one key, a list of keys, or a comma-separated string to trust multiple keys during rotation (see [Key rotation](#key-rotation)). |
 | `heartbeat_mode` | `str \| None` | `None` | Deprecated shim (see [Migrating from heartbeat_mode](#migrating-from-heartbeat_mode)). Use `online_heartbeat` instead. |
 | `heartbeat_interval` | int | `900` | Seconds between background checks (minimum `10`; default 15 min). Applies to both grace period checks and online check-ins. |
@@ -131,7 +131,7 @@ Tune `ttl_seconds` to set the grace period duration (server default 24h, clamped
 
 ## Offline license files (`.authforge`)
 
-For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins.
+For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins. Pass `app_secret=None` (or `""`) so the air-gapped binary does not contain the App Secret.
 
 | | Grace period (default) | Offline license file |
 | --- | --- | --- |
@@ -146,13 +146,13 @@ from authforge import AuthForgeClient
 
 client = AuthForgeClient(
     app_id="YOUR_APP_ID",
-    app_secret="YOUR_APP_SECRET",  # unused for offline files but still required by the constructor
+    app_secret=None,  # login_from_file does not use the App Secret; do not ship it in air-gapped builds
     public_key="YOUR_PUBLIC_KEY",
     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 |

{authforge_sdk-1.2.0 → authforge_sdk-1.3.0}/authforge.py

@@ -80,6 +80,21 @@ OFFLINE_LICENSE_ERRORS = (
     "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.
 
@@ -360,7 +500,7 @@ class AuthForgeClient:
     def __init__(
         self,
         app_id: str,
-        app_secret: str,
+        app_secret: Optional[str],
         public_key: PublicKeyArg,
         heartbeat_mode: Optional[str] = None,
         heartbeat_interval: int = 900,
@@ -374,8 +514,12 @@ class AuthForgeClient:
     ) -> None:
         if not app_id or not isinstance(app_id, str):
             raise ValueError("app_id must be a non-empty string")
-        if not app_secret or not isinstance(app_secret, str):
-            raise ValueError("app_secret must be a non-empty string")
+        # Empty/None is valid for offline-only clients (login_from_file).
+        # Online APIs (login, validate_license, self_ban) still require a secret.
+        if app_secret is None:
+            app_secret = ""
+        elif not isinstance(app_secret, str):
+            raise ValueError("app_secret must be a string or None")
         public_key_list = self._normalize_public_key_list(public_key)
         if not public_key_list:
             raise ValueError(
@@ -459,6 +603,49 @@ class AuthForgeClient:
         """
         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.
@@ -558,9 +745,16 @@ class AuthForgeClient:
             except Exception:
                 pass
 
+    def _require_app_secret(self) -> None:
+        if not self.app_secret:
+            raise ValueError(
+                "app_secret is required for online APIs; omit it only when using login_from_file"
+            )
+
     def login(self, license_key: str) -> bool:
         if not license_key or not isinstance(license_key, str):
             raise ValueError("license_key must be a non-empty string")
+        self._require_app_secret()
 
         try:
             self._validate_and_store(license_key)
@@ -575,6 +769,7 @@ class AuthForgeClient:
         session state or starting the heartbeat thread."""
         if not license_key or not isinstance(license_key, str):
             raise ValueError("license_key must be a non-empty string")
+        self._require_app_secret()
         try:
             body: Dict[str, Any] = {
                 "appId": self.app_id,
@@ -661,6 +856,7 @@ class AuthForgeClient:
         resolved_license = explicit_license or current_license
         if not resolved_license:
             raise ValueError("missing_license_key")
+        self._require_app_secret()
 
         body = {
             "appId": self.app_id,

{authforge_sdk-1.2.0 → authforge_sdk-1.3.0/authforge_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authforge-sdk
-Version: 1.2.0
+Version: 1.3.0
 Summary: Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses.
 Author: AuthForge
 License: MIT
@@ -110,7 +110,7 @@ client = AuthForgeClient(
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `app_id` | str | required | Your application ID from the AuthForge dashboard |
-| `app_secret` | str | required | Your application secret from the AuthForge dashboard |
+| `app_secret` | str | required for online APIs; `None` / `""` for `login_from_file` only | Your application secret from the AuthForge dashboard. Do not ship it in air-gapped binaries. |
 | `public_key` | `str \| Sequence[str]` | required | App Ed25519 public key(s) (base64) from dashboard. Pass one key, a list of keys, or a comma-separated string to trust multiple keys during rotation (see [Key rotation](#key-rotation)). |
 | `heartbeat_mode` | `str \| None` | `None` | Deprecated shim (see [Migrating from heartbeat_mode](#migrating-from-heartbeat_mode)). Use `online_heartbeat` instead. |
 | `heartbeat_interval` | int | `900` | Seconds between background checks (minimum `10`; default 15 min). Applies to both grace period checks and online check-ins. |
@@ -159,7 +159,7 @@ Tune `ttl_seconds` to set the grace period duration (server default 24h, clamped
 
 ## Offline license files (`.authforge`)
 
-For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins.
+For machines that never connect to the internet, the operator mints a **signed offline license file** in the AuthForge dashboard (License page -> *Mint .authforge file*) or via `POST /v1/licenses/{licenseKey}/offline-files`. The file is a standalone Ed25519-signed document; the SDK verifies it with **only** your app public key and the machine HWID. It never contacts AuthForge and never starts online check-ins. Pass `app_secret=None` (or `""`) so the air-gapped binary does not contain the App Secret.
 
 | | Grace period (default) | Offline license file |
 | --- | --- | --- |
@@ -174,13 +174,13 @@ from authforge import AuthForgeClient
 
 client = AuthForgeClient(
     app_id="YOUR_APP_ID",
-    app_secret="YOUR_APP_SECRET",  # unused for offline files but still required by the constructor
+    app_secret=None,  # login_from_file does not use the App Secret; do not ship it in air-gapped builds
     public_key="YOUR_PUBLIC_KEY",
     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"):
@@ -232,6 +232,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 |

{authforge_sdk-1.2.0 → authforge_sdk-1.3.0}/pyproject.toml

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