pwfauth 1.0.0__py3-none-any.whl

pwfauth/__init__.py

@@ -0,0 +1,49 @@
+"""Official Python client for PWF Auth (https://pwfauth.com).
+
+License-key activation, hardware-ID binding, encrypted sessions with a
+server-driven kill switch, free trials, remote texts/slides, and OTA update checks.
+
+    from pwfauth import PwfClient
+    import os, sys
+
+    client = PwfClient(os.environ["PWFAUTH_SECRET"])
+
+    def on_session_ended(error_code, message):
+        print(f"Session ended ({error_code}): {message}", file=sys.stderr)
+        sys.exit(1)
+
+    client.on_session_ended = on_session_ended
+
+    login = client.login("XXXXX-XXXXX-XXXXX-XXXXX")
+    if not login.success:
+        print(login.message, file=sys.stderr)
+        sys.exit(1)
+
+    client.start_heartbeat()   # keeps the session alive AND enforces the kill switch
+
+The hardware ID is derived identically to the .NET and Node clients, so the same
+machine counts as one device no matter which SDK an app uses.
+"""
+
+from .client import PwfClient
+from .envelope import CryptoEnvelope
+from .errors import PwfCryptoError, PwfError, PwfErrorCodes, PwfHttpError, ends_session
+from .hardware_id import get_hardware_id, reset_hardware_id_cache
+from .response import License, PwfResponse
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PwfClient",
+    "PwfResponse",
+    "License",
+    "CryptoEnvelope",
+    "PwfError",
+    "PwfHttpError",
+    "PwfCryptoError",
+    "PwfErrorCodes",
+    "ends_session",
+    "get_hardware_id",
+    "reset_hardware_id_cache",
+    "__version__",
+]

pwfauth/client.py

@@ -0,0 +1,292 @@
+"""The PWF Auth client.
+
+Mirrors the .NET and Node clients: same envelope, same endpoints, same error codes,
+same hardware-ID derivation. Zero dependencies beyond ``cryptography`` -- HTTP goes
+through :mod:`urllib.request` rather than pulling ``requests`` and its four
+transitive dependencies into every app that installs this.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+from .envelope import CryptoEnvelope
+from .errors import PwfError, PwfHttpError, ends_session
+from .hardware_id import get_hardware_id
+from .response import PwfResponse
+
+__all__ = ["PwfClient"]
+
+_DEFAULT_BASE_URL = "https://pwfauth.com"
+
+
+class PwfClient:
+    """A licence client for one application.
+
+    ``on_session_ended`` is the callback that matters: assign a function taking
+    ``(error_code, message)`` and it fires the moment the licence stops being valid
+    on this machine -- a ban, pause, expiry, HWID reset, revoke, maintenance window,
+    or a server that has gone unreachable past the failure budget. Logging alone
+    leaves the licence unenforceable; stop the app there.
+    """
+
+    def __init__(
+        self,
+        app_secret: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        heartbeat_seconds: int = 60,
+        max_heartbeat_failures: int = 3,
+        timeout: float = 15.0,
+        hardware_id: str | None = None,
+    ) -> None:
+        if not app_secret or not isinstance(app_secret, str):
+            raise TypeError("app_secret is required.")
+
+        self.app_secret = app_secret
+        self.base_url = base_url.rstrip("/")
+        self.heartbeat_seconds = heartbeat_seconds
+        self.max_heartbeat_failures = max_heartbeat_failures
+        self.timeout = timeout
+        self.hardware_id = hardware_id or get_hardware_id()
+
+        self.on_session_ended: Callable[[str | None, str | None], None] | None = None
+
+        self._crypto = CryptoEnvelope(app_secret)
+        self._session_id: str | None = None
+        self._license_key: str | None = None
+        self._timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+        self._failures = 0
+
+    # ── state ────────────────────────────────────────────────────────────────
+
+    @property
+    def is_signed_in(self) -> bool:
+        return self._session_id is not None
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    # ── licence lifecycle ────────────────────────────────────────────────────
+
+    def login(self, license_key: str) -> PwfResponse:
+        """Activate a licence key on this machine and open a session."""
+        if not license_key or not isinstance(license_key, str):
+            raise TypeError("license_key is required.")
+        res = self.post_envelope("/api/auth/login.php", {
+            "license_key": license_key,
+            "hwid": self.hardware_id,
+        })
+        if res.success:
+            self._session_id = res.data.get("session_id")
+            self._license_key = license_key
+            self._failures = 0
+        return res
+
+    def check_key(self, license_key: str) -> PwfResponse:
+        """Read a key's state WITHOUT opening a session, so no device seat is used."""
+        if not license_key or not isinstance(license_key, str):
+            raise TypeError("license_key is required.")
+        return self.post_envelope("/api/auth/check-key.php", {
+            "license_key": license_key,
+            "hwid": self.hardware_id,
+        })
+
+    def heartbeat(self) -> PwfResponse:
+        """Send one heartbeat. Raises if called before :meth:`login`."""
+        if not self._session_id:
+            raise PwfError("Not signed in — call login() before heartbeat().")
+        return self.post_envelope("/api/auth/heartbeat.php", {
+            "session_id": self._session_id,
+            "license_key": self._license_key,
+            "hwid": self.hardware_id,
+        })
+
+    def logout(self) -> PwfResponse:
+        """Close the session and free the device seat."""
+        if not self._session_id:
+            raise PwfError("Not signed in.")
+        try:
+            return self.post_envelope("/api/auth/logout.php", {
+                "session_id": self._session_id,
+                "license_key": self._license_key,
+            })
+        finally:
+            self.stop_heartbeat()
+            self._session_id = None
+            self._license_key = None
+
+    # ── heartbeat loop ───────────────────────────────────────────────────────
+
+    def start_heartbeat(self) -> None:
+        """Begin the background heartbeat.
+
+        This is what turns a one-time check into a live session and enforces the
+        kill switch. A daemon timer, so it never keeps the interpreter alive.
+        """
+        if not self._session_id:
+            raise PwfError("Not signed in — call login() before start_heartbeat().")
+        self.stop_heartbeat()
+        self._schedule()
+
+    def stop_heartbeat(self) -> None:
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+
+    def _schedule(self) -> None:
+        with self._lock:
+            self._timer = threading.Timer(self.heartbeat_seconds, self._tick)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _tick(self) -> None:
+        if not self._session_id:
+            return
+        try:
+            res = self.heartbeat()
+        except Exception:
+            # Unreachable server. Tolerate a few in a row — a laptop lid, a train
+            # tunnel, a Wi-Fi handover — then treat it as the session ending, so a
+            # pulled network cable cannot be used to outrun a revoke.
+            self._failures += 1
+            if self._failures >= self.max_heartbeat_failures:
+                self._end_session("NETWORK_LOST", "The license server is unreachable.")
+                return
+            self._schedule()
+            return
+
+        self._failures = 0
+        if not res.success and ends_session(res.error_code):
+            self._end_session(res.error_code, res.message)
+            return
+        # Any other failure is transient (rate limit, a 500) — keep the loop alive.
+        self._schedule()
+
+    def _end_session(self, error_code: str | None, message: str | None) -> None:
+        self.stop_heartbeat()
+        self._session_id = None
+        self._license_key = None
+        if self.on_session_ended:
+            self.on_session_ended(error_code, message)
+
+    # ── app content and updates ──────────────────────────────────────────────
+
+    def get_app_info(self) -> PwfResponse:
+        return self.get_envelope("/api/app/info.php")
+
+    def get_texts(self, license_key: str | None = None) -> PwfResponse:
+        return self.get_envelope("/api/app/text.php", bearer_license_key=license_key)
+
+    def get_slides(self) -> PwfResponse:
+        return self.post_envelope("/api/app/slides.php", {})
+
+    def check_update(self, current_version: str) -> PwfResponse:
+        if not current_version or not isinstance(current_version, str):
+            raise TypeError("current_version is required.")
+        return self.post_envelope("/api/update/check.php", {"version": current_version})
+
+    def track_social_click(self, platform: str) -> PwfResponse:
+        if not platform or not isinstance(platform, str):
+            raise TypeError("platform is required.")
+        return self.post_envelope("/api/app/social-click.php", {"platform": platform})
+
+    # ── plain-JSON endpoints (no envelope) ───────────────────────────────────
+
+    def create_trial(self) -> PwfResponse:
+        return self.post_plain("/api/auth/trial.php", {"hwid": self.hardware_id})
+
+    def request_hardware_reset(self, license_key: str, reason: str = "") -> PwfResponse:
+        if not license_key or not isinstance(license_key, str):
+            raise TypeError("license_key is required.")
+        return self.post_plain("/api/auth/request-hwid-reset.php", {
+            "license_key": license_key,
+            "hwid": self.hardware_id,
+            "reason": reason,
+        })
+
+    def register_account(self, username: str, password: str, license_key: str) -> PwfResponse:
+        return self.post_plain("/api/auth/account-register.php", {
+            "username": username,
+            "password": password,
+            "license_key": license_key,
+            "hwid": self.hardware_id,
+        })
+
+    def account_login(self, username: str, password: str) -> PwfResponse:
+        res = self.post_plain("/api/auth/account-login.php", {
+            "username": username,
+            "password": password,
+            "hwid": self.hardware_id,
+        })
+        if res.success:
+            self._session_id = res.data.get("session_id")
+            self._license_key = (res.license.license_key if res.license else None)
+            self._failures = 0
+        return res
+
+    def change_account_password(self, username: str, old_password: str,
+                                new_password: str) -> PwfResponse:
+        return self.post_plain("/api/auth/change-password.php", {
+            "username": username,
+            "old_password": old_password,
+            "new_password": new_password,
+        })
+
+    # ── transports ───────────────────────────────────────────────────────────
+
+    def post_envelope(self, path: str, body: Any = None) -> PwfResponse:
+        """POST an encrypted envelope and decrypt the reply."""
+        return self._send(path, method="POST",
+                          headers={"Content-Type": "application/json",
+                                   "X-App-Secret": self.app_secret},
+                          data=self._crypto.encrypt(json.dumps(body or {})).encode("utf-8"))
+
+    def get_envelope(self, path: str, bearer_license_key: str | None = None) -> PwfResponse:
+        headers = {"X-App-Secret": self.app_secret}
+        if bearer_license_key:
+            headers["Authorization"] = "Bearer " + bearer_license_key
+        return self._send(path, method="GET", headers=headers, data=None)
+
+    def post_plain(self, path: str, body: Any = None) -> PwfResponse:
+        """POST unencrypted JSON, for the endpoints that do not use the envelope."""
+        return self._send(path, method="POST",
+                          headers={"Content-Type": "application/json",
+                                   "X-App-Secret": self.app_secret},
+                          data=json.dumps(body or {}).encode("utf-8"))
+
+    def _send(self, path: str, *, method: str, headers: dict, data: bytes | None) -> PwfResponse:
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        for k, v in headers.items():
+            req.add_header(k, v)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status = resp.status
+                raw = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            # A 4xx still carries a JSON error envelope worth reading — Cloudflare
+            # eats 5xx bodies, which is why the server uses 4xx for API errors.
+            status = e.code
+            raw = e.read().decode("utf-8", errors="replace")
+        except Exception as cause:
+            raise PwfHttpError(f"Could not reach the license server: {cause}") from cause
+
+        if CryptoEnvelope.looks_like_envelope(raw):
+            raw = self._crypto.decrypt(raw)
+
+        try:
+            return PwfResponse.parse(raw)
+        except PwfError:
+            # Not JSON: an HTML error page from a proxy is the usual cause, so hand
+            # back a snippet instead of "unexpected token <".
+            raise PwfHttpError(
+                f"The license server returned a non-JSON body (HTTP {status}).",
+                status=status, snippet=raw[:200])

pwfauth/envelope.py

@@ -0,0 +1,111 @@
+"""The AES-256-CBC + HMAC-SHA256 envelope the SDK-grade endpoints speak.
+
+Wire format: ``{"p": base64(IV || ciphertext), "t": unix, "s": hmac_hex(p + t)}``.
+Both keys derive from the app secret, so there is no separate key exchange.
+
+This mirrors the server's PayloadCrypto, the .NET client's CryptoEnvelope and the
+Node client's envelope.js **byte for byte** -- all four must stay in lockstep, so
+treat any change here as a protocol change, not an implementation detail.
+
+Python has no AES in its standard library, which is why ``cryptography`` is the one
+dependency this package takes. Everything else is stdlib.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+
+from cryptography.hazmat.primitives import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from .errors import PwfCryptoError
+
+
+class CryptoEnvelope:
+    """Builds and verifies the ``{p,t,s}`` envelope."""
+
+    def __init__(self, app_secret: str, max_drift_seconds: int = 300) -> None:
+        """
+        :param app_secret:       The 64-character hex secret from your dashboard.
+        :param max_drift_seconds: How far a reply's timestamp may drift before it is
+                                  rejected as a replay. Must match the server (300).
+        """
+        if not app_secret:
+            raise TypeError("App secret is required.")
+        self._enc_key = hashlib.sha256(("enc:" + app_secret).encode("utf-8")).digest()
+        self._mac_key = hashlib.sha256(("mac:" + app_secret).encode("utf-8")).digest()
+        self._max_drift = max_drift_seconds
+
+    def encrypt(self, plain_json: str) -> str:
+        """Encrypt a request body into the wire envelope."""
+        if not isinstance(plain_json, str):
+            raise TypeError("plain_json must be a string.")
+
+        iv = os.urandom(16)
+        padder = padding.PKCS7(algorithms.AES.block_size).padder()
+        padded = padder.update(plain_json.encode("utf-8")) + padder.finalize()
+
+        encryptor = Cipher(algorithms.AES(self._enc_key), modes.CBC(iv)).encryptor()
+        ciphertext = encryptor.update(padded) + encryptor.finalize()
+
+        p = base64.b64encode(iv + ciphertext).decode("ascii")
+        t = int(time.time())
+        return json.dumps({"p": p, "t": t, "s": self._hmac_hex(p + str(t))},
+                          separators=(",", ":"))
+
+    def decrypt(self, envelope_json: str) -> str:
+        """Verify and decrypt a wire envelope back into plain JSON.
+
+        :raises PwfCryptoError: signature failed, timestamp drifted, or malformed.
+        """
+        try:
+            obj = json.loads(envelope_json)
+            p, t, s = obj["p"], obj["t"], obj["s"]
+            if not isinstance(p, str) or not isinstance(s, str) or not isinstance(t, int):
+                raise ValueError("missing fields")
+        except Exception as cause:
+            raise PwfCryptoError("Invalid envelope format.") from cause
+
+        if not hmac.compare_digest(self._hmac_hex(p + str(t)), s):
+            raise PwfCryptoError(
+                "HMAC verification failed — wrong app secret, or the payload was tampered with.")
+
+        if abs(int(time.time()) - t) > self._max_drift:
+            raise PwfCryptoError(
+                "Envelope timestamp is outside the accepted window — "
+                "check this machine's system clock.")
+
+        try:
+            combined = base64.b64decode(p, validate=True)
+        except Exception as cause:
+            raise PwfCryptoError("Malformed ciphertext.") from cause
+        if len(combined) <= 16:
+            raise PwfCryptoError("Malformed ciphertext.")
+
+        try:
+            decryptor = Cipher(algorithms.AES(self._enc_key), modes.CBC(combined[:16])).decryptor()
+            padded = decryptor.update(combined[16:]) + decryptor.finalize()
+            unpadder = padding.PKCS7(algorithms.AES.block_size).unpadder()
+            return (unpadder.update(padded) + unpadder.finalize()).decode("utf-8")
+        except Exception as cause:
+            raise PwfCryptoError(
+                "Decryption failed — wrong app secret or corrupted payload.") from cause
+
+    @staticmethod
+    def looks_like_envelope(body: str) -> bool:
+        """True when the document looks like a ``{p,t,s}`` envelope."""
+        if not body:
+            return False
+        try:
+            o = json.loads(body)
+        except Exception:
+            return False
+        return isinstance(o, dict) and "p" in o and "t" in o and "s" in o
+
+    def _hmac_hex(self, message: str) -> str:
+        return hmac.new(self._mac_key, message.encode("utf-8"), hashlib.sha256).hexdigest()

pwfauth/errors.py

@@ -0,0 +1,75 @@
+"""Exception types and the server's error-code vocabulary."""
+
+from __future__ import annotations
+
+
+class PwfError(Exception):
+    """Base class for every error this library raises."""
+
+
+class PwfCryptoError(PwfError):
+    """The encrypted envelope could not be built, verified, or decrypted.
+
+    Usually one of: the wrong app secret, a tampered payload, or a machine clock
+    far enough out of step that the timestamp fell outside the replay window.
+    """
+
+
+class PwfHttpError(PwfError):
+    """The server answered with a non-success status, or a body that was not JSON.
+
+    ``snippet`` carries the first 200 characters of what actually came back, which
+    is what turns "unexpected token <" into "your proxy returned an HTML error page".
+    """
+
+    def __init__(self, message: str, status: int = 0, snippet: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.snippet = snippet
+
+
+class PwfErrorCodes:
+    """Error codes the API returns in ``error_code``.
+
+    Grouped by what the client should DO, not by what went wrong. Anything in
+    :data:`SESSION_ENDING` means the licence is no longer valid on this machine and
+    the app must stop; everything else is worth retrying or reporting.
+    """
+
+    # Licence state — the session is over.
+    KEY_BANNED = "KEY_BANNED"
+    KEY_PAUSED = "KEY_PAUSED"
+    KEY_EXPIRED = "KEY_EXPIRED"
+    KEY_REVOKED = "KEY_REVOKED"
+    KEY_NOT_FOUND = "KEY_NOT_FOUND"
+    HWID_MISMATCH = "HWID_MISMATCH"
+    HWID_RESET = "HWID_RESET"
+    SESSION_EXPIRED = "SESSION_EXPIRED"
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
+    MAINTENANCE = "MAINTENANCE"
+    APP_DISABLED = "APP_DISABLED"
+
+    # Client-side, raised by this library rather than the server.
+    NETWORK_LOST = "NETWORK_LOST"
+
+    # Transient / informational — keep going.
+    RATE_LIMITED = "RATE_LIMITED"
+    SERVER_ERROR = "SERVER_ERROR"
+    INVALID_REQUEST = "INVALID_REQUEST"
+
+    SESSION_ENDING = frozenset({
+        KEY_BANNED, KEY_PAUSED, KEY_EXPIRED, KEY_REVOKED, KEY_NOT_FOUND,
+        HWID_MISMATCH, HWID_RESET, SESSION_EXPIRED, SESSION_NOT_FOUND,
+        MAINTENANCE, APP_DISABLED, NETWORK_LOST,
+    })
+
+
+def ends_session(error_code: str | None) -> bool:
+    """True when this code means the licence is finished on this machine.
+
+    Use it to decide whether to sign the user out. An unknown code returns False on
+    purpose: a code this library has not heard of is far more likely to be a new
+    transient condition than a new way of being banned, and locking users out of a
+    paid app on a guess is the worse failure.
+    """
+    return bool(error_code) and error_code in PwfErrorCodes.SESSION_ENDING

pwfauth/hardware_id.py

@@ -0,0 +1,94 @@
+"""A stable per-machine identifier.
+
+Mirrors the .NET and Node clients exactly, so the same machine produces the same
+HWID under any of the three SDKs. That parity is not cosmetic: a licence counts
+distinct hardware IDs against its device limit, so a mismatch would burn a second
+seat the moment a customer switched SDKs.
+
+Windows reads the cryptography MachineGuid through ``reg.exe`` -- deliberately not
+``wmic``, which Windows 11 24H2 removed. Linux reads ``/etc/machine-id``, macOS the
+IOPlatformUUID. Anything that fails falls back to the host name.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import socket
+import subprocess
+
+_cached: str | None = None
+
+
+def get_hardware_id() -> str:
+    """Return this machine's hardware ID, computing it once per process."""
+    global _cached
+    if _cached is not None:
+        return _cached
+
+    value = ""
+    try:
+        value = _resolve()
+    except Exception:
+        # Any probe failure falls through to the host-name fallback.
+        pass
+
+    _cached = (value or _safe_hostname()).strip()
+    return _cached
+
+
+def reset_hardware_id_cache() -> None:
+    """Clear the cache. Only useful in tests."""
+    global _cached
+    _cached = None
+
+
+def _resolve() -> str:
+    system = platform.system()
+    if system == "Windows":
+        return _windows_machine_guid()
+    if system == "Darwin":
+        return _mac_platform_uuid()
+    for path in ("/etc/machine-id", "/var/lib/dbus/machine-id"):
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as fh:
+                return fh.read().strip()
+    return ""
+
+
+def _windows_machine_guid() -> str:
+    out = _run(["reg", "query", r"HKLM\SOFTWARE\Microsoft\Cryptography", "/v", "MachineGuid"])
+    # "    MachineGuid    REG_SZ    2f5a1c8e-..."
+    marker = out.upper().find("REG_SZ")
+    return "" if marker < 0 else out[marker + len("REG_SZ"):].strip()
+
+
+def _mac_platform_uuid() -> str:
+    out = _run(["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"])
+    m = re.search(r'"IOPlatformUUID"\s*=\s*"([^"]+)"', out)
+    return m.group(1) if m else ""
+
+
+def _run(args: list[str]) -> str:
+    try:
+        # CREATE_NO_WINDOW keeps a console from flashing over a GUI app, the same
+        # concern as windowsHide in the Node client.
+        flags = 0x08000000 if platform.system() == "Windows" else 0
+        out = subprocess.run(
+            args,
+            capture_output=True,
+            timeout=5,
+            creationflags=flags,
+            check=False,
+        )
+        return out.stdout.decode("utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+def _safe_hostname() -> str:
+    try:
+        return socket.gethostname() or "unknown-host"
+    except Exception:
+        return "unknown-host"

pwfauth/response.py

@@ -0,0 +1,123 @@
+"""The parsed reply from the licence server."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .errors import PwfError
+
+
+def _to_datetime(value) -> datetime | None:
+    """Parse the server's timestamps, returning None for anything unusable.
+
+    Lifetime keys send ``expires_at: null``. Returning None rather than raising is
+    deliberate -- treating that null as a date is the single most common integration
+    bug against this API.
+    """
+    if not value or not isinstance(value, str):
+        return None
+    text = value.strip().replace(" ", "T")
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+@dataclass(frozen=True)
+class License:
+    """The licence block from a login reply."""
+
+    license_key: str | None = None
+    key_type: str | None = None
+    duration: int | None = None
+    hwid: str | None = None
+    activated_at: datetime | None = None
+    expires_at: datetime | None = None
+    days_remaining: int | None = None
+    status: str | None = None
+
+    @property
+    def is_lifetime(self) -> bool:
+        """True when the key never expires.
+
+        The library answers this so callers never have to special-case a null date.
+        """
+        return self.expires_at is None
+
+
+@dataclass(frozen=True)
+class PwfResponse:
+    """A licence-server reply, with the raw body kept reachable as fields grow."""
+
+    data: dict = field(default_factory=dict)
+    raw_json: str = ""
+
+    @staticmethod
+    def parse(body: str) -> "PwfResponse":
+        try:
+            data = json.loads(body)
+        except Exception as cause:
+            raise PwfError(
+                "The license server returned a body that is not valid JSON.") from cause
+        if not isinstance(data, dict):
+            raise PwfError("The license server returned a body that is not a JSON object.")
+        return PwfResponse(data=data, raw_json=body)
+
+    @property
+    def success(self) -> bool:
+        """True when the API reported success."""
+        return self.data.get("success") is True
+
+    @property
+    def error_code(self) -> str | None:
+        """Machine-readable failure reason. Compare against :class:`PwfErrorCodes`."""
+        code = self.data.get("error_code")
+        return code if isinstance(code, str) else None
+
+    @property
+    def message(self) -> str | None:
+        """Human-readable message, safe to show the end user."""
+        msg = self.data.get("message")
+        return msg if isinstance(msg, str) else None
+
+    @property
+    def license(self) -> License | None:
+        """The licence block, or None when the reply carries no ``user`` object."""
+        u = self.data.get("user")
+        if not isinstance(u, dict):
+            return None
+        days = u.get("days_remaining")
+        return License(
+            license_key=u.get("license_key"),
+            key_type=u.get("key_type"),
+            duration=u.get("duration"),
+            hwid=u.get("hwid"),
+            activated_at=_to_datetime(u.get("activated_at")),
+            expires_at=_to_datetime(u.get("expires_at")),
+            days_remaining=days if isinstance(days, int) else None,
+            status=u.get("status"),
+        )
+
+    @property
+    def features(self) -> dict:
+        """Per-key feature flags. Empty dict when absent."""
+        f = self.data.get("features")
+        return f if isinstance(f, dict) else {}
+
+    def get_boolean(self, key: str, default: bool = False) -> bool:
+        """Read a feature flag, tolerating the 1/0/"true" forms the panel can store."""
+        if key not in self.features:
+            return default
+        v = self.features[key]
+        if isinstance(v, bool):
+            return v
+        if isinstance(v, (int, float)):
+            return v != 0
+        if isinstance(v, str):
+            return v.strip().lower() in ("1", "true", "yes", "on")
+        return default

pwfauth-1.0.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: pwfauth
+Version: 1.0.0
+Summary: Official Python client for PWF Auth (pwfauth.com): license-key activation, hardware-ID binding, encrypted sessions with a server-driven kill switch, free trials, remote texts/slides, and OTA update checks.
+Project-URL: Homepage, https://pwfauth.com
+Project-URL: Documentation, https://pwfauth.com/api.php
+Project-URL: Repository, https://github.com/pwfauth/pwfauth-python
+Project-URL: Issues, https://github.com/pwfauth/pwfauth-python/issues
+Author: PWF Auth
+License: MIT License
+        
+        Copyright (c) 2026 PWF Auth
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: activation,auth,authentication,drm,hwid,license-key,licensing,pwfauth,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=3.4
+Description-Content-Type: text/markdown
+
+# pwfauth
+
+Official Python client for [PWF Auth](https://pwfauth.com) — license keys, hardware-ID
+binding, encrypted sessions with a server-driven kill switch, free trials, remote
+texts/slides, and OTA update checks.
+
+PWF Auth is **100% free** — every feature, unlimited, forever.
+
+```bash
+pip install pwfauth
+```
+
+Python 3.9+. One dependency (`cryptography`), because Python has no AES in its
+standard library; HTTP uses `urllib` from the stdlib rather than pulling in `requests`.
+
+## Quick start
+
+```python
+import os
+import sys
+from pwfauth import PwfClient
+
+client = PwfClient(os.environ["PWFAUTH_SECRET"])
+
+def on_session_ended(error_code, message):
+    """Ban, pause, expiry, HWID reset, revoke, maintenance, or an unreachable
+    server. Actually stop here — logging alone leaves the licence unenforceable."""
+    print(f"Session ended ({error_code}): {message}", file=sys.stderr)
+    sys.exit(1)
+
+client.on_session_ended = on_session_ended
+
+login = client.login("XXXXX-XXXXX-XXXXX-XXXXX")
+if not login.success:
+    print(login.message, file=sys.stderr)   # safe to show the user
+    sys.exit(1)
+
+client.start_heartbeat()   # keeps the session alive AND enforces the kill switch
+```
+
+`start_heartbeat()` is what turns a one-time check into a live session. Revoke the key
+in your dashboard and `on_session_ended` fires on the user's machine within seconds —
+it does not wait for the next launch.
+
+## Reading the licence
+
+```python
+lic = login.license
+if lic.is_lifetime:
+    print("Lifetime licence")
+else:
+    print(f"Expires {lic.expires_at:%Y-%m-%d} — {lic.days_remaining} day(s) left")
+```
+
+`expires_at` is `None` for lifetime keys — the server sends `expires_at: null`, and
+treating that as a date is the most common integration bug against this API. The
+`is_lifetime` flag exists so you never have to.
+
+## Feature flags
+
+```python
+if login.get_boolean("pro_export"):
+    enable_export()
+```
+
+Handles the `1` / `0` / `"true"` forms the dashboard can store.
+
+## Checking a key without using a device seat
+
+```python
+status = client.check_key(key)   # no session opened, no seat consumed
+```
+
+## Hardware ID
+
+```python
+from pwfauth import get_hardware_id
+print(get_hardware_id())
+```
+
+Derived identically to the [.NET](https://www.nuget.org/packages/PWFAuth) and
+[Node](https://www.npmjs.com/package/pwfauth) clients, so **the same machine counts as
+one device under any SDK** — switching languages does not burn a second seat against
+the licence's device limit.
+
+## Everything else
+
+| Method | What it does |
+| --- | --- |
+| `login(key)` / `logout()` | Open and close a session |
+| `check_key(key)` | Read a key's state without a session |
+| `heartbeat()` | One manual beat |
+| `start_heartbeat()` / `stop_heartbeat()` | The background loop |
+| `create_trial()` | Issue a free trial for this machine |
+| `request_hardware_reset(key, reason)` | Ask an admin to unbind a device |
+| `get_app_info()` / `get_texts()` / `get_slides()` | Remote app content |
+| `check_update(version)` | OTA update check |
+| `register_account()` / `account_login()` / `change_account_password()` | User accounts |
+| `post_envelope()` / `get_envelope()` / `post_plain()` | Raw transports |
+
+## Error codes
+
+```python
+from pwfauth import PwfErrorCodes, ends_session
+
+if ends_session(res.error_code):
+    sign_out()
+```
+
+`ends_session()` returns `False` for a code it does not recognise, on purpose: an
+unknown code is far more likely to be a new transient condition than a new way of
+being banned, and locking a paying user out on a guess is the worse failure.
+
+## Links
+
+- [Dashboard](https://pwfauth.com) · [API reference](https://pwfauth.com/api.php)
+- [.NET client](https://www.nuget.org/packages/PWFAuth) · [Node client](https://www.npmjs.com/package/pwfauth) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=PWFAuth.pwfauth)
+
+MIT

pwfauth-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pwfauth/__init__.py,sha256=W61RzVUvNF5sKGpePmrTp5dmYZetfQ9tBTK5qomCT8k,1445
+pwfauth/client.py,sha256=CZY-s-gs3FUN4TaGUHHWX8dWogHQMgtbPHXhuGx25ME,12491
+pwfauth/envelope.py,sha256=S4LZyPyBA4uAWofwkniMtsgQZbY2HFovlq-hwGrm4QI,4654
+pwfauth/errors.py,sha256=y4feYoNOisZIQN_7f_Bqr6XcZYVdu32tnwbB1zbEgo0,2668
+pwfauth/hardware_id.py,sha256=zMcjwf-Q1Rf7iZrrnlSA9MQuFUMr2iDT4qRoEm8vVSk,2776
+pwfauth/response.py,sha256=mQ7tvFIEH64_fyWmK3xwcrEkUXiKX5ot1Yhd6w62fdw,4072
+pwfauth-1.0.0.dist-info/METADATA,sha256=iXs9PTCq_6lz0t4qtVCti2GYT11FL7cGX4bt5oYT3LQ,6437
+pwfauth-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pwfauth-1.0.0.dist-info/licenses/LICENSE,sha256=14ZkQljXYT8S_M1UPsaMP2wJbbk__tbhlBE1CamDSi4,1065
+pwfauth-1.0.0.dist-info/RECORD,,

pwfauth-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pwfauth-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PWF Auth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.