icare-licensing 1.0.0__py3-none-any.whl

icare_licensing-1.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: icare-licensing
+Version: 1.0.0
+Summary: Secure cryptographic offline-first licensing client library for Icare licensing system
+Author: Icare Infosystems
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: license.lic
+License-File: license_metadata.json
+Requires-Dist: requests>=2.25.0
+Requires-Dist: cryptography>=3.0.0
+Dynamic: license-file
+
+# Icare Licensing Client
+
+`icare-liecensing-client` is an offline-first, cryptographically secure licensing client library for Python applications. It integrates seamlessly with the Icare licensing server using RSA-SHA256 signatures, device hardware bindings, and automated offline-resilient sync policies.
+
+---
+
+## Features
+- **Stable Hardware Binding (HWID)**: Generates a stable machine signature.
+- **Offline Cryptographic Validation**: Validates license state offline using RSA-SHA256.
+- **Automated Sync Daemon**: Runs in the background and pings the verification endpoint every 24 hours.
+- **3-Day Offline Grace Period**: Remains fully functional offline for up to 3 days before requiring internet.
+- **Instant Revocation Purge**: Deletes local signatures and metadata immediately upon server-side license revocation or deletion to prevent offline bypass.
+
+---
+
+## 1. Installation
+
+Install the package from your PyPI registry:
+```bash
+pip install icare-licensing
+```
+
+---
+
+## 2. License Storage & File Location Policy
+
+By default, the client library writes `license.lic` and `license_metadata.json` relative to the **Current Working Directory (CWD)** of the executing process.
+
+### Critical Production Guidelines
+For desktop deployments or system-wide CLI tools, running relative to the CWD can lead to:
+1. **Permission Denials (`PermissionError`)**: If the app is run from a read-only directory (e.g. `Program Files` or `/usr/local/bin`).
+2. **Missing Licenses**: If the user starts the application from a different terminal directory, the client will look in the wrong path and report the license is missing.
+
+### Recommendation: Use Absolute Paths
+Always initialize the client with an **absolute path** pointing to a user-writable application directory (such as the user's home folder or standard application data directory).
+
+```python
+import os
+from licensing_client import LicensingClient
+
+# Determine a safe system path (e.g., ~/.config/my_app/ or %APPDATA%/my_app/)
+app_folder = os.path.join(os.path.expanduser("~"), ".my_app")
+os.makedirs(app_folder, exist_ok=True)
+
+license_path = os.path.join(app_folder, "license.lic")
+
+# Initialize client
+client = LicensingClient(
+    server_url="https://licensing.mycompany.com",
+    license_file_path=license_path
+)
+```
+*Note: The metadata file (`license_metadata.json`) will automatically be generated in the same target folder.*
+
+---
+
+## 3. Core Developer API
+
+### Licensing States
+The library exposes six core status constants:
+* `STATUS_VALID`: License signature is cryptographically valid, matches machine HWID, is not expired, and is synced.
+* `STATUS_MISSING`: No `license.lic` file is present (Device needs activation).
+* `STATUS_EXPIRED`: The local or server expiration date has been exceeded.
+* `STATUS_INVALID`: The license cryptographic signature is corrupt, has been modified, or has been actively revoked/deleted on the server.
+* `STATUS_REQUIRES_SYNC`: The application has been running offline for more than 3 days and requires internet to refresh.
+* `STATUS_UNKNOWN`: State is not yet resolved.
+
+---
+
+## 4. Integration Template
+
+Copy this robust integration template into your project's main entry point:
+
+```python
+import os
+import sys
+from licensing_client import (
+    LicensingClient,
+    STATUS_VALID,
+    STATUS_REQUIRES_SYNC,
+    STATUS_MISSING,
+    STATUS_INVALID,
+    STATUS_EXPIRED
+)
+
+def on_license_status_change(new_status):
+    """
+    Callback triggered when the license status transitions.
+    NOTE: If running a GUI application (e.g., Tkinter/PyQt), make sure 
+    to route UI-altering updates safely to the main thread.
+    """
+    print(f"[Licensing] Status changed to: {new_status}")
+    
+    if new_status == STATUS_VALID:
+        print("Premium features unlocked!")
+        # Proceed to launch normal application logic
+        
+    elif new_status == STATUS_REQUIRES_SYNC:
+        print("Warning: internet connection required to verify license.")
+        # Optional: Show a warning banner, but keep standard features unlocked
+        
+    elif new_status in (STATUS_MISSING, STATUS_INVALID, STATUS_EXPIRED):
+        print("Security Lock: No valid license active.")
+        # Action: Redirect user to your license activation overlay/screen
+        # Lock down core software capabilities
+
+def main():
+    # 1. Setup secure storage paths
+    app_folder = os.path.join(os.path.expanduser("~"), ".my_app")
+    os.makedirs(app_folder, exist_ok=True)
+    license_path = os.path.join(app_folder, "license.lic")
+
+    # 2. Instantiate Client
+    # max_offline_days determines how long the app can run offline (default: 3 days)
+    client = LicensingClient(
+        server_url="http://localhost:8081",
+        license_file_path=license_path,
+        status_callback=on_license_status_change,
+        max_offline_days=3
+    )
+
+    # 3. Handle Initial State
+    # Force a check immediately on startup
+    client._run_check()
+
+    if client.current_status == STATUS_MISSING:
+        print("Application is unactivated.")
+        # Example: prompt user for activation key in CLI
+        # key = input("Enter Activation Key: ")
+        # success, msg = client.activate_device(key)
+
+    # 4. Start Background Protection Thread
+    # Validates locally and checks online every 5 minutes (300 seconds)
+    client.start_monitoring(interval_seconds=300)
+
+if __name__ == "__main__":
+    main()
+```

icare_licensing-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+licensing_client.py,sha256=-oWG34VUx5TGQDafCMCljH9KTXscECQBbu2G0jkoA1k,17247
+icare_licensing-1.0.0.dist-info/licenses/license.lic,sha256=WG0_fKN8wUai1WkF_Ab5FDOt6j1q8gsnMTC3gTQjIEg,205
+icare_licensing-1.0.0.dist-info/licenses/license_metadata.json,sha256=Lkb9xaIF4vBfNhGykUYIajMekO5Dk0cN7lh6Fr8WjRo,199
+icare_licensing-1.0.0.dist-info/METADATA,sha256=HGbtjKF6kZAwufAHyzCUb5aLEONx_iUqyOyjGbP1ueE,6063
+icare_licensing-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+icare_licensing-1.0.0.dist-info/top_level.txt,sha256=i-_Wemc8QhosRnFSyK0gVfMETpdwvklOtIZC2jjSM7U,17
+icare_licensing-1.0.0.dist-info/RECORD,,

icare_licensing-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

icare_licensing-1.0.0.dist-info/licenses/license.lic

@@ -0,0 +1 @@
+bGljZW5zZUlkPTEwO3N0YXJ0RGF0ZT0yMDI2LTA1LTIyIDE4OjIzOjA5O3ZhbGlkRGF5cz0zNjU7aGFyZHdhcmVJZD1IVy1CNjVBNTBCOEVCMjJGMzk2.W5O/Ffr9TQkLbu0S8von0xktvU8UOkUTcQSveas7Pj1cOScUE3y1X/HsMHUQ3ZlKZUa6iXFU3oWo789tPbKeHw==

icare_licensing-1.0.0.dist-info/licenses/license_metadata.json

@@ -0,0 +1,4 @@
+{
+    "public_key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIxJO7zOoJgqTDHspY+t1jBfBuxce5sOQ0GyrXzuxLW6pp2/lleFdDXyNDaYkdgp8Pl4VW7XjGkL/fTrC5p2LasCAwEAAQ==",
+    "last_server_sync": 1779603544.7417145
+}

icare_licensing-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+licensing_client

licensing_client.py

@@ -0,0 +1,403 @@
+import os
+import json
+import time
+import uuid
+import platform
+import hashlib
+import base64
+import threading
+from datetime import datetime, timedelta
+import requests
+
+# Cryptography dependencies for RSA signature verification
+try:
+    from cryptography.hazmat.primitives.asymmetric import padding
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.serialization import load_der_public_key
+    CRYPTOGRAPHY_AVAILABLE = True
+except ImportError:
+    CRYPTOGRAPHY_AVAILABLE = False
+
+# Licensing Status Constants
+STATUS_VALID = "VALID"
+STATUS_EXPIRED = "EXPIRED"
+STATUS_MISSING = "MISSING"
+STATUS_INVALID = "INVALID"
+STATUS_REQUIRES_SYNC = "REQUIRES_SYNC"
+STATUS_UNKNOWN = "UNKNOWN"
+
+class LicensingClient:
+    def __init__(self, server_url, license_file_path="license.lic", status_callback=None, max_offline_days=3):
+        """
+        Initializes the Licensing Client.
+        
+        :param server_url: Base URL of the Spring Boot Licensing Server (e.g. 'http://localhost:8081')
+        :param license_file_path: File path where the signed compact license key is stored
+        :param status_callback: Callable function triggered when the license status transitions
+        :param max_offline_days: Number of days the client can run offline before requiring a sync
+        """
+        self.server_url = server_url.rstrip("/")
+        self.license_file_path = license_file_path
+        self.status_callback = status_callback
+        self.max_offline_days = max_offline_days
+        
+        self.metadata_file_path = f"{os.path.splitext(self.license_file_path)[0]}_metadata.json"
+        
+        self.current_status = STATUS_UNKNOWN
+        self.public_key_b64 = None
+        self.last_server_sync = 0.0
+        
+        self._stop_event = threading.Event()
+        self._lock = threading.Lock()
+        
+        # Load local cached metadata on initialization
+        self._load_local_metadata()
+
+    @staticmethod
+    def get_hardware_id():
+        """
+        Generates a cross-platform, consistent, and unique Hardware ID for the host machine.
+        
+        :return: String representing unique Hardware ID (e.g., 'HW-E8C2F1A039B4725E')
+        """
+        node = uuid.getnode()
+        system = platform.system()
+        machine = platform.machine()
+        processor = platform.processor()
+        
+        # Combine system parameters into a stable raw string
+        system_info = f"{node}-{system}-{machine}-{processor}"
+        sha_hash = hashlib.sha256(system_info.encode("utf-8")).hexdigest()
+        
+        return f"HW-{sha_hash[:16].upper()}"
+
+    def activate_device(self, activation_key):
+        """
+        [SYNCHRONOUS] Activates the device by binding the activation key placeholder 
+        to the local machine's generated Hardware ID.
+        
+        :param activation_key: The Base64 placeholder code issued by the admin.
+        :return: (bool success, str message)
+        """
+        hw_id = self.get_hardware_id()
+        activation_url = f"{self.server_url}/api/v1/licenses/activate"
+        payload = {
+            "activationKey": activation_key.strip(),
+            "hardwareID": hw_id
+        }
+        
+        try:
+            # 1. Fetch public key first to ensure we can verify the signature
+            self._fetch_public_key()
+            
+            # 2. Call activation endpoint
+            response = requests.post(activation_url, json=payload, timeout=8)
+            response_json = response.json()
+            
+            if response.status_code == 200 and response_json.get("success"):
+                response_list = response_json.get("responseList", [])
+                if response_list:
+                    license_data = response_list[0]
+                    license_key = license_data.get("licenseKey")
+                    
+                    if license_key:
+                        # Save the compact signed license key locally
+                        with open(self.license_file_path, "w", encoding="utf-8") as f:
+                            f.write(license_key)
+                        
+                        # Update metadata status
+                        self.last_server_sync = time.time()
+                        self._save_local_metadata()
+                        
+                        # Recalculate status immediately
+                        self._run_check()
+                        return True, "Device bound and activated successfully!"
+            
+            error_message = response_json.get("message", "Device activation failed.")
+            return False, error_message
+            
+        except Exception as e:
+            return False, f"Activation request failed: {str(e)}"
+
+    def start_monitoring(self, interval_seconds=300):
+        """
+        Spawns the periodic licensing verification loop on a background daemon thread.
+        
+        :param interval_seconds: Background check interval in seconds (default is 5 minutes).
+        """
+        if not CRYPTOGRAPHY_AVAILABLE:
+            raise ImportError(
+                "The 'cryptography' library is required to run the LicensingClient. "
+                "Please install it using: pip install cryptography"
+            )
+            
+        self._stop_event.clear()
+        monitor_thread = threading.Thread(
+            target=self._monitor_loop,
+            args=(interval_seconds,),
+            daemon=True
+        )
+        monitor_thread.start()
+
+    def stop_monitoring(self):
+        """Stops the background verification loop cleanly."""
+        self._stop_event.set()
+
+    def _monitor_loop(self, interval):
+        """Background thread main monitoring loop."""
+        # Perform immediate validation check on startup
+        self._run_check()
+        
+        # Loop periodically until thread shutdown event is set
+        while not self._stop_event.is_set():
+            self._stop_event.wait(interval)
+            if not self._stop_event.is_set():
+                self._run_check()
+
+    def _run_check(self, force_online=False):
+        """Runs the verification logic and triggers the developer callback on state transition."""
+        with self._lock:
+            new_status = self._perform_verification(force_online=force_online)
+            if new_status != self.current_status:
+                self.current_status = new_status
+                if self.status_callback:
+                    try:
+                        self.status_callback(new_status)
+                    except Exception as e:
+                        print(f"[LicensingClient] Error in developer status callback: {e}")
+
+    def _perform_verification(self, force_online=False):
+        """
+        Performs full licensing licensing_verification:
+        1. Checks for file presence
+        2. Validates RSA cryptographic signature offline
+        3. Validates hardware mapping and expiry timeline offline
+        4. Calculates force sync-timeout (3 days)
+        5. Synchronizes with server online (every 24 hours or if requires sync)
+        """
+        # 1. Check if license file exists
+        if not os.path.exists(self.license_file_path):
+            return STATUS_MISSING
+
+        try:
+            # Read local license file
+            with open(self.license_file_path, "r", encoding="utf-8") as f:
+                license_key = f.read().strip()
+            
+            parts = license_key.split(".")
+            if len(parts) != 2:
+                return STATUS_INVALID
+                
+            readable_b64, signature_b64 = parts[0], parts[1]
+            
+            # Decode the base64 readable payload to parse variables
+            try:
+                payload_str = base64.b64decode(readable_b64).decode("utf-8")
+            except Exception:
+                return STATUS_INVALID
+                
+            # Parse payload variables (e.g. licenseId=X;startDate=Y;validDays=Z;hardwareId=W)
+            params = {}
+            for segment in payload_str.split(";"):
+                if "=" in segment:
+                    k, v = segment.split("=", 1)
+                    params[k] = v
+                    
+            required_keys = ["licenseId", "startDate", "validDays", "hardwareId"]
+            if not all(k in params for k in required_keys):
+                return STATUS_INVALID
+                
+            # 2. Local Hardware Binding Check
+            local_hw_id = self.get_hardware_id()
+            if params["hardwareId"] != local_hw_id:
+                return STATUS_INVALID
+                
+            # 3. Local Expiration Timeline Check
+            try:
+                start_date = datetime.strptime(params["startDate"], "%Y-%m-%d %H:%M:%S")
+                valid_days = int(params["validDays"])
+                expiration_date = start_date + timedelta(days=valid_days)
+            except Exception:
+                return STATUS_INVALID
+                
+            if datetime.now() > expiration_date:
+                return STATUS_EXPIRED
+                
+            # Ensure we have the public key loaded
+            if not self.public_key_b64:
+                # Try fetching from server or metadata cache
+                self._fetch_public_key()
+                if not self.public_key_b64:
+                    return STATUS_INVALID
+            
+            # 4. Cryptographic RSA Signature Offline Validation
+            signature_valid = self._verify_rsa_signature(readable_b64, signature_b64)
+            if not signature_valid:
+                return STATUS_INVALID
+
+            # 5. Online Verification Sync Checks (Scheduled 24h & Sync-Timeout 3d)
+            now = time.time()
+            elapsed_since_sync = now - self.last_server_sync
+            
+            # 24 Hours in seconds = 86,400 seconds
+            sync_interval_elapsed = elapsed_since_sync >= 24 * 3600
+            
+            # Perform online check if:
+            # - We are forcing an online check (e.g. manual verification click)
+            # - 24 hours have passed since the last successful sync
+            if force_online or sync_interval_elapsed:
+                sync_result = self._perform_online_sync(license_key)
+                if sync_result == "SUCCESS":
+                    return STATUS_VALID
+                elif sync_result == "REJECTED":
+                    # Actively rejected by the server! Immediately lock and invalidate client!
+                    # Purge local files and metadata so local offline validation is permanently blocked
+                    try:
+                        if os.path.exists(self.license_file_path):
+                            os.remove(self.license_file_path)
+                    except Exception as e:
+                        print(f"[LicensingClient] Failed to delete rejected license file: {e}")
+                    
+                    try:
+                        if os.path.exists(self.metadata_file_path):
+                            os.remove(self.metadata_file_path)
+                    except Exception as e:
+                        print(f"[LicensingClient] Failed to delete metadata file: {e}")
+                        
+                    self.last_server_sync = 0.0
+                    self.public_key_b64 = None
+                    return STATUS_INVALID
+                # If sync_result is "OFFLINE", we continue to the offline fallback!
+                    
+            # 3 Days in seconds = 259,200 seconds
+            offline_limit_elapsed = elapsed_since_sync >= self.max_offline_days * 24 * 3600
+            if offline_limit_elapsed:
+                # We've been offline too long! Force sync status transition.
+                return STATUS_REQUIRES_SYNC
+                
+            # Otherwise, the offline verification is completely valid!
+            return STATUS_VALID
+
+        except Exception:
+            return STATUS_INVALID
+
+    def _verify_rsa_signature(self, readable_b64, signature_b64):
+        """Cryptographically verifies the SHA256withRSA signature offline using the cached public key."""
+        if not CRYPTOGRAPHY_AVAILABLE:
+            return False
+            
+        try:
+            public_key_bytes = base64.b64decode(self.public_key_b64)
+            public_key = load_der_public_key(public_key_bytes)
+            
+            sig_bytes = base64.b64decode(signature_b64)
+            payload_bytes = readable_b64.encode("utf-8")
+            
+            public_key.verify(
+                sig_bytes,
+                payload_bytes,
+                padding.PKCS1v15(),
+                hashes.SHA256()
+            )
+            return True
+        except Exception:
+            return False
+
+    def _perform_online_sync(self, license_key):
+        """
+        Pings the online verify endpoint to synchronize license state.
+        Returns:
+            "SUCCESS" if verified and valid on the server.
+            "REJECTED" if server is online and actively rejected it (revoked/deactivated/deleted).
+            "OFFLINE" if the server is unreachable (temporary network downtime).
+        """
+        verify_url = f"{self.server_url}/api/v1/licenses/verify"
+        payload = {"licenseKey": license_key}
+        
+        try:
+            response = requests.post(verify_url, json=payload, timeout=5)
+            
+            # Case A: Active Success
+            if response.status_code == 200:
+                try:
+                    response_json = response.json()
+                    if response_json.get("success"):
+                        response_list = response_json.get("responseList", [])
+                        if response_list:
+                            server_license = response_list[0]
+                            # Check if backend reports key is active and not disabled
+                            if server_license.get("status") == "ACTIVE" and server_license.get("active") == 1:
+                                # Update sync time and cache
+                                self.last_server_sync = time.time()
+                                self._save_local_metadata()
+                                return "SUCCESS"
+                            else:
+                                # Server successfully responded, but license is not active/enabled (e.g. pending, deactivated, expired)
+                                return "REJECTED"
+                except Exception:
+                    pass
+
+            # Case B: Active Server Rejection
+            # If server actively returns 400 Bad Request or 404 Not Found (e.g. from IllegalArgumentException)
+            # or returned a valid JSON with success=False, it means the server processed the key and found it invalid.
+            if response.status_code == 400 or response.status_code == 404 or response.status_code == 403:
+                return "REJECTED"
+                
+            try:
+                response_json = response.json()
+                if response_json.get("success") is False:
+                    return "REJECTED"
+            except Exception:
+                pass
+                
+            # If the HTTP status is between 400 and 499, treat as REJECTED
+            if 400 <= response.status_code < 500:
+                return "REJECTED"
+                
+            # Case C: Offline or temporary Server Error
+            # Treating 5xx server errors as OFFLINE ensures transient backend issues don't lock out valid paying clients.
+            return "OFFLINE"
+            
+        except requests.exceptions.RequestException:
+            # Server is unreachable (Connection error, timeout, DNS failure)
+            return "OFFLINE"
+        except Exception:
+            return "OFFLINE"
+
+    def _fetch_public_key(self):
+        """Fetches the active public key from the Spring Boot server and saves it to local cache."""
+        public_key_url = f"{self.server_url}/api/v1/licenses/public-key"
+        try:
+            response = requests.get(public_key_url, timeout=4)
+            response_json = response.json()
+            if response.status_code == 200 and response_json.get("success"):
+                response_list = response_json.get("responseList", [])
+                if response_list:
+                    self.public_key_b64 = response_list[0]
+                    self._save_local_metadata()
+        except Exception:
+            # Fail silently to support local cached fallback
+            pass
+
+    def _load_local_metadata(self):
+        """Loads cached public key and last sync timestamp from a secure metadata JSON file."""
+        if os.path.exists(self.metadata_file_path):
+            try:
+                with open(self.metadata_file_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                    self.public_key_b64 = data.get("public_key")
+                    self.last_server_sync = data.get("last_server_sync", 0.0)
+            except Exception:
+                pass
+
+    def _save_local_metadata(self):
+        """Saves current public key and last sync timestamp to local metadata cache."""
+        try:
+            data = {
+                "public_key": self.public_key_b64,
+                "last_server_sync": self.last_server_sync
+            }
+            with open(self.metadata_file_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=4)
+        except Exception:
+            pass