keymint 2.1.0__tar.gz → 2.2.0__tar.gz

{keymint-2.1.0/keymint.egg-info → keymint-2.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: keymint
-Version: 2.1.0
+Version: 2.2.0
 Summary: Official Python SDK for KeyMint license management with comprehensive API coverage.
 Home-page: https://github.com/keymint-dev/keymint-python
 Author: KeyMint
-Author-email: admin@keymint.dev
+Author-email: cliff@keymint.dev
 Project-URL: Bug Reports, https://github.com/keymint-dev/keymint-python/issues
 Project-URL: Source, https://github.com/keymint-dev/keymint-python
 Project-URL: Documentation, https://docs.keymint.dev/sdks/python
@@ -47,15 +47,15 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# KeyMint Python SDK
+# Keymint Python
 
-A professional, production-ready SDK for integrating with the KeyMint API in Python. Provides robust access to all major KeyMint features, with type hints and modern error handling.
+A professional, production-ready SDK for integrating with the Keymint API in Python. Provides robust access to all major Keymint features, with type hints and modern error handling.
 
 ## Features
 - **Type hints**: Full type hint support for better IDE integration and code safety.
-- **Comprehensive**: Complete API coverage for all KeyMint endpoints.
+- **Comprehensive**: Complete API coverage for all Keymint endpoints.
 - **Consistent error handling**: All API errors are returned as structured objects or exceptions.
-- **Security**: Credentials are always loaded from environment variables.
+- **Machine Identity**: Built-in utilities for hardware fingerprinting and stable installation IDs.
 
 ## Installation
 Add the SDK to your project:
@@ -68,32 +68,36 @@ pip install keymint
 
 ```python
 import os
-import keymint
+from keymint import KeyMint, identity
 
-access_token = os.environ.get('KEYMINT_ACCESS_TOKEN')
+api_key = os.environ.get('KEYMINT_API_KEY')
 product_id = os.environ.get('KEYMINT_PRODUCT_ID')
 
-if not access_token or not product_id:
-    raise ValueError('Please set the KEYMINT_ACCESS_TOKEN and KEYMINT_PRODUCT_ID environment variables.')
+if not api_key or not product_id:
+    raise ValueError('Please set the KEYMINT_API_KEY and KEYMINT_PRODUCT_ID environment variables.')
 
-sdk = keymint.KeyMint(access_token)
+sdk = KeyMint(api_key)
+
+# 1. Get a stable, unique ID for this machine
+host_id = identity.get_or_create_installation_id()
+
+# 2. Create a key authorized only for this machine
+result = sdk.create_key({ 
+    'productId': product_id,
+    'allowedHosts': [host_id]
+})
 
-# Example: Create a key
-result = sdk.create_key({ 'productId': product_id })
 if result and 'key' in result:
-    key = result['key']
-    # ...
-else:
-    # Handle error
-    pass
+    print(f"Created Key: {result['key']}")
 ```
 
-## Error Handling
-All SDK methods return a dictionary. If an API call fails, the SDK raises a `KeyMintApiError` exception with `message`, `code`, and `status` attributes.
+## Machine Identity
+Keymint provides utilities to uniquely identify machines for node-locking:
 
-## API Methods
+- `identity.get_or_create_installation_id()`: **Recommended.** Generates a stable UUID anchored to hardware and persists it to `~/.keymint/installation-id`.
+- `identity.get_machine_id()`: Generates a SHA-256 fingerprint based on BIOS UUID, OS machine ID, and MAC address.
 
-All methods return a dictionary.
+## API Methods
 
 ### License Key Management
 
@@ -105,6 +109,9 @@ All methods return a dictionary.
 | `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
 
@@ -118,10 +125,14 @@ All methods return a dictionary.
 | `toggle_customer_status`| Toggles customer active status.                  |
 | `delete_customer`       | Permanently deletes a customer and their keys.   |
 
-For detailed parameter and response types, see the [KeyMint API docs](https://docs.keymint.dev) or use your IDE's autocomplete.
+### Webhook Verification
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `verify_webhook_signature`| Verifies the signature of a webhook request payload. |
 
 ## License
 MIT
 
 ## Support
-For help, see [KeyMint API docs](https://docs.keymint.dev) or open an issue.
+For help, see [Keymint API docs](https://docs.keymint.dev) or open an issue.

{keymint-2.1.0 → keymint-2.2.0}/README.md

@@ -1,12 +1,12 @@
-# KeyMint Python SDK
+# Keymint Python
 
-A professional, production-ready SDK for integrating with the KeyMint API in Python. Provides robust access to all major KeyMint features, with type hints and modern error handling.
+A professional, production-ready SDK for integrating with the Keymint API in Python. Provides robust access to all major Keymint features, with type hints and modern error handling.
 
 ## Features
 - **Type hints**: Full type hint support for better IDE integration and code safety.
-- **Comprehensive**: Complete API coverage for all KeyMint endpoints.
+- **Comprehensive**: Complete API coverage for all Keymint endpoints.
 - **Consistent error handling**: All API errors are returned as structured objects or exceptions.
-- **Security**: Credentials are always loaded from environment variables.
+- **Machine Identity**: Built-in utilities for hardware fingerprinting and stable installation IDs.
 
 ## Installation
 Add the SDK to your project:
@@ -19,32 +19,36 @@ pip install keymint
 
 ```python
 import os
-import keymint
+from keymint import KeyMint, identity
 
-access_token = os.environ.get('KEYMINT_ACCESS_TOKEN')
+api_key = os.environ.get('KEYMINT_API_KEY')
 product_id = os.environ.get('KEYMINT_PRODUCT_ID')
 
-if not access_token or not product_id:
-    raise ValueError('Please set the KEYMINT_ACCESS_TOKEN and KEYMINT_PRODUCT_ID environment variables.')
+if not api_key or not product_id:
+    raise ValueError('Please set the KEYMINT_API_KEY and KEYMINT_PRODUCT_ID environment variables.')
 
-sdk = keymint.KeyMint(access_token)
+sdk = KeyMint(api_key)
+
+# 1. Get a stable, unique ID for this machine
+host_id = identity.get_or_create_installation_id()
+
+# 2. Create a key authorized only for this machine
+result = sdk.create_key({ 
+    'productId': product_id,
+    'allowedHosts': [host_id]
+})
 
-# Example: Create a key
-result = sdk.create_key({ 'productId': product_id })
 if result and 'key' in result:
-    key = result['key']
-    # ...
-else:
-    # Handle error
-    pass
+    print(f"Created Key: {result['key']}")
 ```
 
-## Error Handling
-All SDK methods return a dictionary. If an API call fails, the SDK raises a `KeyMintApiError` exception with `message`, `code`, and `status` attributes.
+## Machine Identity
+Keymint provides utilities to uniquely identify machines for node-locking:
 
-## API Methods
+- `identity.get_or_create_installation_id()`: **Recommended.** Generates a stable UUID anchored to hardware and persists it to `~/.keymint/installation-id`.
+- `identity.get_machine_id()`: Generates a SHA-256 fingerprint based on BIOS UUID, OS machine ID, and MAC address.
 
-All methods return a dictionary.
+## API Methods
 
 ### License Key Management
 
@@ -56,6 +60,9 @@ All methods return a dictionary.
 | `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
 
@@ -69,10 +76,14 @@ All methods return a dictionary.
 | `toggle_customer_status`| Toggles customer active status.                  |
 | `delete_customer`       | Permanently deletes a customer and their keys.   |
 
-For detailed parameter and response types, see the [KeyMint API docs](https://docs.keymint.dev) or use your IDE's autocomplete.
+### Webhook Verification
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `verify_webhook_signature`| Verifies the signature of a webhook request payload. |
 
 ## License
 MIT
 
 ## Support
-For help, see [KeyMint API docs](https://docs.keymint.dev) or open an issue.
+For help, see [Keymint API docs](https://docs.keymint.dev) or open an issue.

{keymint-2.1.0 → keymint-2.2.0}/keymint/__init__.py

@@ -5,14 +5,14 @@ from ._version import __version__
 __all__ = ['KeyMint', 'KeyMintApiError', '__version__']
 
 class KeyMint:
-    def __init__(self, access_token: str, base_url: str = "https://api.keymint.dev"):
-        if not access_token:
-            raise ValueError("Access token is required to initialize the SDK.")
+    def __init__(self, api_key: str, base_url: str = "https://api.keymint.dev"):
+        if not api_key:
+            raise ValueError("API key is required to initialize the SDK.")
         
-        self.access_token = access_token
+        self.api_key = api_key
         self.base_url = base_url
         self.headers = {
-            'Authorization': f'Bearer {self.access_token}',
+            'Authorization': f'Bearer {self.api_key}',
             'Content-Type': 'application/json'
         }
 
@@ -79,6 +79,30 @@ class KeyMint:
         """
         return self._handle_request('POST', '/key/deactivate', params)
 
+    def floating_checkout(self, params: FloatingCheckoutParams) -> FloatingCheckoutResponse:
+        """
+        Checks out a floating license seat.
+        :param params: Parameters for checking out the license.
+        :returns: The checkout response containing sessionId and sessionSecret.
+        """
+        return self._handle_request('POST', '/key/checkout', params)
+
+    def floating_heartbeat(self, params: FloatingHeartbeatParams) -> FloatingHeartbeatResponse:
+        """
+        Sends a heartbeat to keep a floating license session alive.
+        :param params: Parameters for the heartbeat (includes rotating signature).
+        :returns: The heartbeat response with extended expiry and new nonce.
+        """
+        return self._handle_request('POST', '/key/heartbeat', params)
+
+    def floating_checkin(self, params: FloatingCheckinParams) -> FloatingCheckinResponse:
+        """
+        Checks in a floating license session, releasing the seat.
+        :param params: Parameters for checking in the license (includes rotating signature).
+        :returns: The checkin confirmation.
+        """
+        return self._handle_request('POST', '/key/checkin', params)
+
     def get_key(self, params: GetKeyParams) -> GetKeyResponse:
         """
         Retrieves detailed information about a specific license key.
@@ -169,3 +193,60 @@ class KeyMint:
         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-2.1.0 → keymint-2.2.0}/keymint/_version.py

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

{keymint-2.1.0 → keymint-2.2.0}/keymint/identity.py

@@ -7,6 +7,7 @@ Provides two methods for identifying machines:
 """
 
 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-2.1.0 → keymint-2.2.0}/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

{keymint-2.1.0 → keymint-2.2.0/keymint.egg-info}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: keymint
-Version: 2.1.0
+Version: 2.2.0
 Summary: Official Python SDK for KeyMint license management with comprehensive API coverage.
 Home-page: https://github.com/keymint-dev/keymint-python
 Author: KeyMint
-Author-email: admin@keymint.dev
+Author-email: cliff@keymint.dev
 Project-URL: Bug Reports, https://github.com/keymint-dev/keymint-python/issues
 Project-URL: Source, https://github.com/keymint-dev/keymint-python
 Project-URL: Documentation, https://docs.keymint.dev/sdks/python
@@ -47,15 +47,15 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# KeyMint Python SDK
+# Keymint Python
 
-A professional, production-ready SDK for integrating with the KeyMint API in Python. Provides robust access to all major KeyMint features, with type hints and modern error handling.
+A professional, production-ready SDK for integrating with the Keymint API in Python. Provides robust access to all major Keymint features, with type hints and modern error handling.
 
 ## Features
 - **Type hints**: Full type hint support for better IDE integration and code safety.
-- **Comprehensive**: Complete API coverage for all KeyMint endpoints.
+- **Comprehensive**: Complete API coverage for all Keymint endpoints.
 - **Consistent error handling**: All API errors are returned as structured objects or exceptions.
-- **Security**: Credentials are always loaded from environment variables.
+- **Machine Identity**: Built-in utilities for hardware fingerprinting and stable installation IDs.
 
 ## Installation
 Add the SDK to your project:
@@ -68,32 +68,36 @@ pip install keymint
 
 ```python
 import os
-import keymint
+from keymint import KeyMint, identity
 
-access_token = os.environ.get('KEYMINT_ACCESS_TOKEN')
+api_key = os.environ.get('KEYMINT_API_KEY')
 product_id = os.environ.get('KEYMINT_PRODUCT_ID')
 
-if not access_token or not product_id:
-    raise ValueError('Please set the KEYMINT_ACCESS_TOKEN and KEYMINT_PRODUCT_ID environment variables.')
+if not api_key or not product_id:
+    raise ValueError('Please set the KEYMINT_API_KEY and KEYMINT_PRODUCT_ID environment variables.')
 
-sdk = keymint.KeyMint(access_token)
+sdk = KeyMint(api_key)
+
+# 1. Get a stable, unique ID for this machine
+host_id = identity.get_or_create_installation_id()
+
+# 2. Create a key authorized only for this machine
+result = sdk.create_key({ 
+    'productId': product_id,
+    'allowedHosts': [host_id]
+})
 
-# Example: Create a key
-result = sdk.create_key({ 'productId': product_id })
 if result and 'key' in result:
-    key = result['key']
-    # ...
-else:
-    # Handle error
-    pass
+    print(f"Created Key: {result['key']}")
 ```
 
-## Error Handling
-All SDK methods return a dictionary. If an API call fails, the SDK raises a `KeyMintApiError` exception with `message`, `code`, and `status` attributes.
+## Machine Identity
+Keymint provides utilities to uniquely identify machines for node-locking:
 
-## API Methods
+- `identity.get_or_create_installation_id()`: **Recommended.** Generates a stable UUID anchored to hardware and persists it to `~/.keymint/installation-id`.
+- `identity.get_machine_id()`: Generates a SHA-256 fingerprint based on BIOS UUID, OS machine ID, and MAC address.
 
-All methods return a dictionary.
+## API Methods
 
 ### License Key Management
 
@@ -105,6 +109,9 @@ All methods return a dictionary.
 | `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
 
@@ -118,10 +125,14 @@ All methods return a dictionary.
 | `toggle_customer_status`| Toggles customer active status.                  |
 | `delete_customer`       | Permanently deletes a customer and their keys.   |
 
-For detailed parameter and response types, see the [KeyMint API docs](https://docs.keymint.dev) or use your IDE's autocomplete.
+### Webhook Verification
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `verify_webhook_signature`| Verifies the signature of a webhook request payload. |
 
 ## License
 MIT
 
 ## Support
-For help, see [KeyMint API docs](https://docs.keymint.dev) or open an issue.
+For help, see [Keymint API docs](https://docs.keymint.dev) or open an issue.

{keymint-2.1.0 → keymint-2.2.0}/setup.py

@@ -5,9 +5,9 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="keymint",
-    version="2.1.0",
+    version="2.2.0",
     author="KeyMint",
-    author_email="admin@keymint.dev",
+    author_email="cliff@keymint.dev",
     description="Official Python SDK for KeyMint license management with comprehensive API coverage.",
     long_description=long_description,
     long_description_content_type="text/markdown",