chore: bump version to 2.2.0 and add verify_webhook_signature & floating licensing support

Author: catsika

.github/workflows/ci-cd.yml

@@ -0,0 +1,58 @@
+name: Python SDK CI/CD
+
+on:
+  pull_request:
+    branches: [ main, master ]
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  validate:
+    name: Build & Validate Python SDK
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies & tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff build
+
+      - name: Run Ruff (Linter & Formatter)
+        run: ruff check .
+
+      - name: Verify Package Build
+        run: python -m build
+
+  publish:
+    name: Publish to PyPI
+    needs: validate
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write # Required for Trusted Publishing OIDC
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -60,6 +60,9 @@ Keymint provides utilities to uniquely identify machines for node-locking:
 | `get_key`        | Retrieves detailed information about a key.     |
 | `block_key`      | Blocks a license key.                           |
 | `unblock_key`    | Unblocks a previously blocked license key.      |
+| `floating_checkout` | Checks out a floating license seat.          |
+| `floating_heartbeat`| Sends a heartbeat to keep a session alive.   |
+| `floating_checkin`  | Checks in a session, releasing the seat.     |
 
 ### Customer Management
 
@@ -73,6 +76,12 @@ Keymint provides utilities to uniquely identify machines for node-locking:
 | `toggle_customer_status`| Toggles customer active status.                  |
 | `delete_customer`       | Permanently deletes a customer and their keys.   |
 
+### Webhook Verification
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `verify_webhook_signature`| Verifies the signature of a webhook request payload. |
+
 ## License
 MIT
 

keymint/__init__.py

@@ -193,3 +193,60 @@ def toggle_customer_status(self, params: ToggleCustomerStatusParams) -> ToggleCu
         query_params = {'customerId': params['customerId']}
         return self._handle_request('POST', '/customer/disable', params=None, query_params=query_params)
 
+    @staticmethod
+    def verify_webhook_signature(payload: str, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
+        """
+        Verifies a webhook payload signature received from Keymint.
+        :param payload: The raw request body as a string.
+        :param header: The value of the "Keymint-Signature" header.
+        :param secret: The webhook endpoint's signing secret.
+        :param tolerance_seconds: Time tolerance in seconds to prevent replay attacks. Defaults to 300 (5 minutes).
+        :returns: True if the signature is valid, False otherwise.
+        """
+        import hmac
+        import hashlib
+        import time
+
+        if not header or not secret:
+            return False
+
+        try:
+            # Parse header (e.g. t=1719374021,v1=signature)
+            timestamp_str = ""
+            signature = ""
+            parts = header.split(",")
+            for part in parts:
+                kv = part.strip().split("=", 1)
+                if len(kv) == 2:
+                    if kv[0] == "t":
+                        timestamp_str = kv[1]
+                    elif kv[0] == "v1":
+                        signature = kv[1]
+
+            if not timestamp_str or not signature:
+                return False
+
+            # Check timestamp validity
+            try:
+                timestamp_int = int(timestamp_str)
+            except ValueError:
+                return False
+
+            now = int(time.time())
+            if abs(now - timestamp_int) > tolerance_seconds:
+                return False
+
+            # Verify HMAC signature
+            signable_content = f"{timestamp_str}.{payload}".encode("utf-8")
+            expected_signature = hmac.new(
+                secret.encode("utf-8"),
+                signable_content,
+                hashlib.sha256
+            ).hexdigest()
+
+            # Constant-time comparison to prevent timing attacks
+            return hmac.compare_digest(expected_signature, signature)
+        except Exception:
+            return False
+
+

keymint/_version.py

@@ -1,6 +1,6 @@
 """KeyMint Python SDK version information."""
 
-__version__ = "2.1.1"
+__version__ = "2.2.0"
 __author__ = "KeyMint"
 __email__ = "cliff@keymint.dev"
 __url__ = "https://github.com/keymint-dev/keymint-python"

keymint/identity.py

@@ -7,6 +7,7 @@
 """
 
 import hashlib
+import hmac
 import os
 import platform
 import subprocess
@@ -195,7 +196,27 @@ def get_or_create_installation_id(storage_path: Optional[str] = None) -> str:
     composite_id = f'{new_uuid}:{hardware_anchor}:{int(time.time() * 1000)}'
 
     # 3. Persist it
-    file_path.parent.mkdir(parents=True, exist_ok=True)
-    file_path.write_text(composite_id, encoding='utf-8')
+    try:
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(composite_id, encoding='utf-8')
+    except Exception:
+        pass  # Silently fallback to in-memory ID if filesystem is read-only
 
     return hashlib.sha256(composite_id.encode('utf-8')).hexdigest()
+
+def generate_session_signature(session_id: str, nonce: str, session_secret: str) -> str:
+    """
+    Generates a cryptographic signature for a heartbeat or checkin request
+    using the session_secret and the rotating nextNonce (passed as the timestamp).
+
+    Args:
+        session_id: The 22-character unique session ID.
+        nonce: The rotating nonce string (nextNonce) received from the previous response.
+        session_secret: The temporary session secret key received during checkout.
+
+    Returns:
+        A 64-character hexadecimal signature string.
+    """
+    key_bytes = session_secret.encode('utf-8')
+    msg_bytes = f"{session_id}:{nonce}".encode('utf-8')
+    return hmac.new(key_bytes, msg_bytes, hashlib.sha256).hexdigest()

keymint/types.py

@@ -187,3 +187,51 @@ class GetCustomerWithKeysResponse(TypedDict):
     status: bool
     data: Dict[str, Any]  # Contains customer and licenseKeys
     code: int
+
+class FloatingCheckoutParams(TypedDict):
+    productId: str
+    licenseKey: str
+    hostId: str
+    deviceTag: Optional[str]
+    userIdentifier: Optional[str]
+    apiKey: Optional[str]
+
+class FloatingCheckoutResponse(TypedDict):
+    code: int
+    message: str
+    sessionId: str
+    sessionSecret: str
+    nextNonce: str
+    expiresAt: str
+    heartbeatInterval: int
+    metadata: Optional[Dict[str, Any]]
+    currentSessions: Optional[int]
+    maxSessions: Optional[int]
+    licenseeName: Optional[str]
+    licenseeEmail: Optional[str]
+
+class FloatingHeartbeatParams(TypedDict):
+    productId: str
+    licenseKey: str
+    sessionId: str
+    timestamp: Any  # rotating nonce (nextNonce) received from previous response
+    signature: str
+    apiKey: Optional[str]
+
+class FloatingHeartbeatResponse(TypedDict):
+    code: int
+    message: str
+    expiresAt: str
+    nextNonce: str
+
+class FloatingCheckinParams(TypedDict):
+    productId: str
+    licenseKey: str
+    sessionId: str
+    timestamp: Any  # rotating nonce (nextNonce) received from previous response
+    signature: str
+    apiKey: Optional[str]
+
+class FloatingCheckinResponse(TypedDict):
+    code: int
+    message: str

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="keymint",
-    version="2.1.1",
+    version="2.2.0",
     author="KeyMint",
     author_email="cliff@keymint.dev",
     description="Official Python SDK for KeyMint license management with comprehensive API coverage.",