keymint 2.5.0__tar.gz → 2.7.0__tar.gz

{keymint-2.5.0/keymint.egg-info → keymint-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keymint
-Version: 2.5.0
+Version: 2.7.0
 Summary: License key validation, activation, and management for Python. Supports node-locking, offline licensing, and hardware fingerprinting.
 Home-page: https://github.com/keymint-dev/keymint-python
 Author: KeyMint
@@ -24,6 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.32.4
+Requires-Dist: cryptography>=41
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -51,6 +52,7 @@ A professional, production-ready SDK for integrating with the Keymint API in Pyt
 - **Type hints**: Full type hint support for better IDE integration and code safety.
 - **Comprehensive**: Complete API coverage for all Keymint endpoints.
 - **Consistent error handling**: All API errors are returned as structured objects or exceptions.
+- **Offline licenses**: Verify signed `.lic` files locally with `verify_offline_license`.
 - **Machine Identity**: Built-in utilities for hardware fingerprinting and stable installation IDs.
 
 ## Installation
@@ -87,6 +89,105 @@ if result and 'key' in result:
     print(f"Created Key: {result['key']}")
 ```
 
+## License Expiry
+
+`activate_key` and `floating_checkout` return `expirationDate`: the license expiry as an ISO 8601 string (e.g. `"2027-03-01T00:00:00.000Z"`), or `None` when the license never expires. On `floating_checkout`, `expiresAt` is the seat lease, not the license expiry.
+
+```python
+from datetime import datetime, timezone
+import math
+
+result = sdk.activate_key({'productId': product_id, 'licenseKey': license_key, 'hostId': host_id})
+
+expiration = result.get('expirationDate')
+if expiration is None:
+    print('License never expires')
+else:
+    expires_at = datetime.fromisoformat(expiration.replace('Z', '+00:00'))
+    seconds_left = (expires_at - datetime.now(timezone.utc)).total_seconds()
+    days_left = max(0, math.ceil(seconds_left / 86400))
+    print(f'License expires {expires_at:%Y-%m-%d} ({days_left} days left)')
+
+# Store the last value you received (e.g. in your app's settings file).
+```
+
+Store the last `expirationDate` you received. An expired license fails activation with the same generic invalid-key error as a wrong key, so the stored date is how your app can tell the user the license expired on that date instead of calling the key invalid.
+
+## Offline Licenses
+
+An offline license is a `.lic` file holding a token signed with your organization's Ed25519 key. Your app verifies it locally with `verify_offline_license`, with no network call.
+
+1. **Get the `.lic` file** from the dashboard's Offline License dialog, or with `sign_key` from your own backend (it needs an admin API key, so never call it from the shipped app). The `hostId` you sign for becomes the license's machine code, so use the ID the customer's machine reports, e.g. `identity.get_or_create_installation_id()`.
+
+   ```python
+   # On your server, with host_id sent by the customer's machine:
+   result = sdk.sign_key({'productId': product_id, 'licenseKey': license_key, 'hostId': host_id})
+   lic = result['file']  # the .lic contents; deliver this to the customer
+   ```
+
+2. **Bundle your public key** with the app: copy the PEM from **Developer → Public Keys** in the dashboard. It is a public key, so shipping it is safe.
+
+3. **Verify** with the product ID and this machine's code:
+
+   ```python
+   from keymint import OfflineLicenseError, identity, verify_offline_license
+
+   PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
+   MCowBQYDK2VwAyEA...
+   -----END PUBLIC KEY-----
+   """
+
+   with open('license.lic', encoding='utf-8') as f:
+       lic = f.read()
+
+   try:
+       offline = verify_offline_license(
+           lic,
+           public_keys=[PUBLIC_KEY],
+           product_id='prod_...',  # this app's product ID
+           machine_code=identity.get_or_create_installation_id(),
+       )
+       print(f'Licensed until {offline.expires_at:%Y-%m-%d}')
+   except OfflineLicenseError as err:
+       if err.code == 'expired':
+           ...  # ask the customer to renew or reconnect
+       elif err.code in ('wrong_product', 'wrong_machine'):
+           ...  # a real license, but not for this product or this machine
+       else:
+           ...  # malformed, unsupported_algorithm, unknown_key, bad_signature, wrong_type: not a valid license
+   ```
+
+`verify_offline_license` accepts the `.lic` file contents or the bare token and returns an `OfflineLicense` with `license_key`, `product_id`, `machine_code`, `key_id`, `issued_at` (or `None`) and `expires_at` (timezone-aware UTC datetimes). On failure it raises `OfflineLicenseError`; `err.code` is one of:
+
+| Code | Meaning |
+|---|---|
+| `malformed` | Not a license file or token, or required claims (`exp`, `sub`) are missing or invalid. |
+| `unsupported_algorithm` | The token is not signed with EdDSA (e.g. `none`, `HS256`). |
+| `unknown_key` | Signed by a key that isn't in `public_keys`. |
+| `bad_signature` | The signature doesn't match: the file was altered or forged. |
+| `wrong_type` | The token is not an offline license. |
+| `wrong_product` | The license is for a different product. |
+| `wrong_machine` | The license is for a different machine. |
+| `expired` | Past its expiry, plus `clock_skew` (default 60 seconds, max 3600). |
+
+Bad arguments (no public keys, a PEM that isn't an Ed25519 public key, an empty `product_id` or `machine_code`, `clock_skew` outside 0..3600, a naive `now`) raise `ValueError` or `TypeError`, not `OfflineLicenseError`.
+
+**`product_id` is required.** One signing key covers all of an organization's products, so without the product check a license for a cheap product would unlock an expensive one.
+
+**Clock rollback.** The SDK can't tell if the system clock was set back. To guard against it, store the latest time you have trusted (for example, after each successful run) and pass the later of the two as `now`. `now` must be timezone-aware:
+
+```python
+from datetime import datetime, timezone
+
+now = max(datetime.now(timezone.utc), last_trusted_time)
+offline = verify_offline_license(lic, public_keys=[PUBLIC_KEY], product_id=product_id,
+                                 machine_code=machine_code, now=now)
+```
+
+`public_keys` accepts several keys, so apps are ready for key rotation. An offline license stays valid until it expires; it can't be revoked before then.
+
+Offline verification uses the [`cryptography`](https://pypi.org/project/cryptography/) package, which `pip install keymint` installs (`cryptography>=41`).
+
 ## Machine Identity
 Keymint provides utilities to uniquely identify machines for node-locking:
 
@@ -106,6 +207,7 @@ Keymint provides utilities to uniquely identify machines for node-locking:
 | `update_key`     | Updates an existing license key.                |
 | `block_key`      | Blocks a license key.                           |
 | `unblock_key`    | Unblocks a previously blocked license key.      |
+| `delete_key`     | Permanently deletes a license key.              |
 | `sign_key`       | Signs a key for offline validation using an admin API key.|
 | `floating_checkout` | Checks out a floating license seat.          |
 | `floating_heartbeat`| Sends a heartbeat to keep a session alive.   |
@@ -121,7 +223,7 @@ Keymint provides utilities to uniquely identify machines for node-locking:
 | `get_customer_with_keys`| Gets a customer along with their license keys.   |
 | `update_customer`       | Updates customer information.                    |
 | `toggle_customer_status`| Toggles customer active status.                  |
-| `delete_customer`       | Permanently deletes a customer and their keys.   |
+| `delete_customer`       | Deletes a customer. Their license keys are kept; use `delete_key` to remove them. |
 
 ### Webhook Verification
 

keymint-2.7.0/README.md

@@ -0,0 +1,202 @@
+# 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.
+
+## Features
+- **Type hints**: Full type hint support for better IDE integration and code safety.
+- **Comprehensive**: Complete API coverage for all Keymint endpoints.
+- **Consistent error handling**: All API errors are returned as structured objects or exceptions.
+- **Offline licenses**: Verify signed `.lic` files locally with `verify_offline_license`.
+- **Machine Identity**: Built-in utilities for hardware fingerprinting and stable installation IDs.
+
+## Installation
+Add the SDK to your project:
+
+```bash
+pip install keymint
+```
+
+## Usage
+
+```python
+import os
+from keymint import KeyMint, identity
+
+api_key = os.environ.get('KEYMINT_API_KEY')
+product_id = os.environ.get('KEYMINT_PRODUCT_ID')
+
+if not api_key or not product_id:
+    raise ValueError('Please set the KEYMINT_API_KEY and KEYMINT_PRODUCT_ID environment variables.')
+
+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]
+})
+
+if result and 'key' in result:
+    print(f"Created Key: {result['key']}")
+```
+
+## License Expiry
+
+`activate_key` and `floating_checkout` return `expirationDate`: the license expiry as an ISO 8601 string (e.g. `"2027-03-01T00:00:00.000Z"`), or `None` when the license never expires. On `floating_checkout`, `expiresAt` is the seat lease, not the license expiry.
+
+```python
+from datetime import datetime, timezone
+import math
+
+result = sdk.activate_key({'productId': product_id, 'licenseKey': license_key, 'hostId': host_id})
+
+expiration = result.get('expirationDate')
+if expiration is None:
+    print('License never expires')
+else:
+    expires_at = datetime.fromisoformat(expiration.replace('Z', '+00:00'))
+    seconds_left = (expires_at - datetime.now(timezone.utc)).total_seconds()
+    days_left = max(0, math.ceil(seconds_left / 86400))
+    print(f'License expires {expires_at:%Y-%m-%d} ({days_left} days left)')
+
+# Store the last value you received (e.g. in your app's settings file).
+```
+
+Store the last `expirationDate` you received. An expired license fails activation with the same generic invalid-key error as a wrong key, so the stored date is how your app can tell the user the license expired on that date instead of calling the key invalid.
+
+## Offline Licenses
+
+An offline license is a `.lic` file holding a token signed with your organization's Ed25519 key. Your app verifies it locally with `verify_offline_license`, with no network call.
+
+1. **Get the `.lic` file** from the dashboard's Offline License dialog, or with `sign_key` from your own backend (it needs an admin API key, so never call it from the shipped app). The `hostId` you sign for becomes the license's machine code, so use the ID the customer's machine reports, e.g. `identity.get_or_create_installation_id()`.
+
+   ```python
+   # On your server, with host_id sent by the customer's machine:
+   result = sdk.sign_key({'productId': product_id, 'licenseKey': license_key, 'hostId': host_id})
+   lic = result['file']  # the .lic contents; deliver this to the customer
+   ```
+
+2. **Bundle your public key** with the app: copy the PEM from **Developer → Public Keys** in the dashboard. It is a public key, so shipping it is safe.
+
+3. **Verify** with the product ID and this machine's code:
+
+   ```python
+   from keymint import OfflineLicenseError, identity, verify_offline_license
+
+   PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
+   MCowBQYDK2VwAyEA...
+   -----END PUBLIC KEY-----
+   """
+
+   with open('license.lic', encoding='utf-8') as f:
+       lic = f.read()
+
+   try:
+       offline = verify_offline_license(
+           lic,
+           public_keys=[PUBLIC_KEY],
+           product_id='prod_...',  # this app's product ID
+           machine_code=identity.get_or_create_installation_id(),
+       )
+       print(f'Licensed until {offline.expires_at:%Y-%m-%d}')
+   except OfflineLicenseError as err:
+       if err.code == 'expired':
+           ...  # ask the customer to renew or reconnect
+       elif err.code in ('wrong_product', 'wrong_machine'):
+           ...  # a real license, but not for this product or this machine
+       else:
+           ...  # malformed, unsupported_algorithm, unknown_key, bad_signature, wrong_type: not a valid license
+   ```
+
+`verify_offline_license` accepts the `.lic` file contents or the bare token and returns an `OfflineLicense` with `license_key`, `product_id`, `machine_code`, `key_id`, `issued_at` (or `None`) and `expires_at` (timezone-aware UTC datetimes). On failure it raises `OfflineLicenseError`; `err.code` is one of:
+
+| Code | Meaning |
+|---|---|
+| `malformed` | Not a license file or token, or required claims (`exp`, `sub`) are missing or invalid. |
+| `unsupported_algorithm` | The token is not signed with EdDSA (e.g. `none`, `HS256`). |
+| `unknown_key` | Signed by a key that isn't in `public_keys`. |
+| `bad_signature` | The signature doesn't match: the file was altered or forged. |
+| `wrong_type` | The token is not an offline license. |
+| `wrong_product` | The license is for a different product. |
+| `wrong_machine` | The license is for a different machine. |
+| `expired` | Past its expiry, plus `clock_skew` (default 60 seconds, max 3600). |
+
+Bad arguments (no public keys, a PEM that isn't an Ed25519 public key, an empty `product_id` or `machine_code`, `clock_skew` outside 0..3600, a naive `now`) raise `ValueError` or `TypeError`, not `OfflineLicenseError`.
+
+**`product_id` is required.** One signing key covers all of an organization's products, so without the product check a license for a cheap product would unlock an expensive one.
+
+**Clock rollback.** The SDK can't tell if the system clock was set back. To guard against it, store the latest time you have trusted (for example, after each successful run) and pass the later of the two as `now`. `now` must be timezone-aware:
+
+```python
+from datetime import datetime, timezone
+
+now = max(datetime.now(timezone.utc), last_trusted_time)
+offline = verify_offline_license(lic, public_keys=[PUBLIC_KEY], product_id=product_id,
+                                 machine_code=machine_code, now=now)
+```
+
+`public_keys` accepts several keys, so apps are ready for key rotation. An offline license stays valid until it expires; it can't be revoked before then.
+
+Offline verification uses the [`cryptography`](https://pypi.org/project/cryptography/) package, which `pip install keymint` installs (`cryptography>=41`).
+
+## Machine Identity
+Keymint provides utilities to uniquely identify machines for node-locking:
+
+- `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.
+
+## API Methods
+
+### License Key Management
+
+| Method           | Description                                     |
+|------------------|-------------------------------------------------|
+| `create_key`     | Creates a new license key.                      |
+| `activate_key`   | Activates a license key for a device.           |
+| `deactivate_key` | Deactivates a device from a license key.        |
+| `get_key`        | Retrieves detailed information about a key.     |
+| `update_key`     | Updates an existing license key.                |
+| `block_key`      | Blocks a license key.                           |
+| `unblock_key`    | Unblocks a previously blocked license key.      |
+| `delete_key`     | Permanently deletes a license key.              |
+| `sign_key`       | Signs a key for offline validation using an admin API 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
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `create_customer`       | Creates a new customer.                          |
+| `get_all_customers`     | Retrieves all customers.                         |
+| `get_customer_by_id`    | Gets a specific customer by ID.                  |
+| `get_customer_with_keys`| Gets a customer along with their license keys.   |
+| `update_customer`       | Updates customer information.                    |
+| `toggle_customer_status`| Toggles customer active status.                  |
+| `delete_customer`       | Deletes a customer. Their license keys are kept; use `delete_key` to remove them. |
+
+### Webhook Verification
+
+| Method                  | Description                                      |
+|-------------------------|--------------------------------------------------|
+| `verify_webhook_signature`| Verifies the signature of a webhook request payload. |
+
+## Idempotency
+
+All mutating SDK methods support idempotency keys to safely retry requests in case of network drops. Pass a unique string (recommended: UUID v4) as the optional `idempotency_key` keyword argument:
+
+```python
+result = sdk.create_key({ 
+    'productId': product_id,
+}, idempotency_key='9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d')
+```
+
+## License
+MIT
+
+## Support
+For help, see [Keymint API docs](https://docs.keymint.dev) or open an issue.

{keymint-2.5.0 → keymint-2.7.0}/keymint/__init__.py

@@ -1,9 +1,23 @@
 import requests
 
 from ._version import __version__
+from .offline import (
+    OfflineLicense,
+    OfflineLicenseError,
+    OfflineLicenseErrorCode,
+    verify_offline_license,
+)
 from .types import *
 
-__all__ = ['KeyMint', 'KeyMintApiError', '__version__']
+__all__ = [
+    'KeyMint',
+    'KeyMintApiError',
+    'OfflineLicense',
+    'OfflineLicenseError',
+    'OfflineLicenseErrorCode',
+    '__version__',
+    'verify_offline_license',
+]
 
 class KeyMint:
     def __init__(self, api_key: str, base_url: str = "https://api.keymint.dev"):
@@ -17,7 +31,8 @@ class KeyMint:
             'Content-Type': 'application/json'
         }
 
-    def _handle_request(self, method: str, endpoint: str, params: dict | None = None, query_params: dict | None = None, idempotency_key: str | None = None, extra_headers: dict | None = None):
+    def _handle_request(self, method: str, endpoint: str, params: dict | None = None, query_params: dict | None = None, idempotency_key: str | None = None, extra_headers: dict | None = None, delete_body: dict | None = None):
+        # DELETE sends a JSON body only when delete_body is given (delete_key).
         url = f'{self.base_url}{endpoint}'
         headers = self.headers.copy()
         if idempotency_key:
@@ -35,7 +50,10 @@ class KeyMint:
             elif method.upper() == 'PATCH':
                 response = requests.patch(url, json=params, params=query_params, headers=headers)
             elif method.upper() == 'DELETE':
-                response = requests.delete(url, params=query_params, headers=headers)
+                if delete_body is not None:
+                    response = requests.delete(url, json=delete_body, params=query_params, headers=headers)
+                else:
+                    response = requests.delete(url, params=query_params, headers=headers)
             else:
                 raise ValueError(f"Unsupported HTTP method: {method}")
             
@@ -79,7 +97,10 @@ class KeyMint:
         
         :param params: Activation parameters including productId, licenseKey, and optional hostId.
         :param idempotency_key: Optional unique identifier to ensure request idempotency.
-        :return: Activation success message and licensee information.
+        :return: Activation success message and licensee information. Includes
+            ``expirationDate``: the license expiry as an ISO 8601 string, or ``None``
+            when the license never expires. An expired license fails activation with
+            the same generic invalid-key error, so store the last value you received.
         """
         return self._handle_request('POST', '/key/activate', params, idempotency_key=idempotency_key)
 
@@ -98,6 +119,8 @@ class KeyMint:
         :param params: Parameters for checking out the license.
         :param idempotency_key: Optional unique identifier to ensure request idempotency.
         :returns: The checkout response containing sessionId and sessionSecret.
+            ``expiresAt`` is the seat lease; ``expirationDate`` is the license expiry
+            as an ISO 8601 string, or ``None`` when the license never expires.
         """
         return self._handle_request('POST', '/key/checkout', params, idempotency_key=idempotency_key)
 
@@ -151,6 +174,16 @@ class KeyMint:
         """
         return self._handle_request('POST', '/key/unblock', params, idempotency_key=idempotency_key)
 
+    def delete_key(self, params: DeleteKeyParams, idempotency_key: str | None = None) -> DeleteKeyResponse:
+        """
+        Permanently deletes a license key. Use block_key to stop a key reversibly.
+        :param params: Parameters for deleting the key.
+        :param idempotency_key: Optional unique identifier to ensure request idempotency.
+        :returns: The deletion confirmation.
+        """
+        body = {'productId': params['productId'], 'licenseKey': params['licenseKey']}
+        return self._handle_request('DELETE', '/key', idempotency_key=idempotency_key, delete_body=body)
+
     def update_key(self, params: 'UpdateKeyParams', idempotency_key: str | None = None) -> 'UpdateKeyResponse':
         """
         Updates an existing license key.
@@ -210,7 +243,7 @@ class KeyMint:
 
     def delete_customer(self, params: DeleteCustomerParams, idempotency_key: str | None = None) -> DeleteCustomerResponse:
         """
-        Permanently deletes a customer and all associated license keys.
+        Deletes a customer. Their license keys are kept; use delete_key to remove them.
         :param params: Parameters containing the customer ID.
         :param idempotency_key: Optional unique identifier to ensure request idempotency.
         :returns: The deletion confirmation.

{keymint-2.5.0 → keymint-2.7.0}/keymint/_version.py

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