QuantumLock™ SDK Reference

Complete reference for the QuantumLock™ Python license validation SDK.

Package: quantumlock-sdk Version: 1.0.0 Python: ≥ 3.9

Overview

The QuantumLock™ SDK is a local license validation library. It validates .lic files on the client side without API calls, ensuring:

🔐 Complete offline validation (zero latency)
⚡ Local quantum signature verification
🔌 2-line code integration
🌍 Works without internet

Important: The SDK does not generate licenses. To generate licenses, use the API REST or the CLI. The SDK is for validating licenses in your end-customer software.

Installation

pip install quantumlock-sdk

Dependencies

requests ≥ 2.31.0 (only for optional online validation)

Step-by-Step Guide

Complete Flow: From generation to validation

┌──────────────────────┐         ┌──────────────────────┐
│   YOUR INFRASTRUCTURE │         │  CUSTOMER SOFTWARE  │
│                      │         │                      │
│  1. Generate licenses    │  .lic   │  3. Validate licenses  │
│     via API/CLI      │ ──────► │     with the SDK        │
│                      │         │                      │
│  2. Distribute the      │         │  4. Gate features    │
│     .lic file     │         │     by license      │
└──────────────────────┘         └──────────────────────┘

Step 1: Generate a license (API or CLI)

# Via CLI
quantumlock generate \
  --customer "customer@company.com" \
  --features "premium,analytics" \
  --days 365 \
  --output license.json

Passo 2: Converta e distribua o .lic file

The .lic file is a JSON (optionally Base64-encoded) containing:

{
  "license_key": "QCOS-41FB-639F-C30B-14E3-6342-7B3E-6426-9320",
  "quantum_signature": "a1b2c3d4e5f6...",
  "customer_id": "customer@company.com",
  "features": ["premium", "analytics"],
  "valid_until": "2026-06-15T10:30:00",
  "security_level": "Quantum-QCOS-16Q",
  "qcos_fingerprint": {
    "fidelity": 0.9847
  }
}

Distribute this file along with the customer software.

Step 3: Validate in the customer software

from quantumlock_sdk import LicenseValidator

validator = LicenseValidator()

if validator.validate("/etc/myapp/license.lic"):
    print("✓ License valid!")
else:
    print("✗ Invalid license!")

Passo 4: Gate features by license

from quantumlock_sdk import LicenseValidator, FeatureNotLicensed

validator = LicenseValidator("/etc/myapp/license.lic")
validator.validate()

# Check specific feature
if validator.has_feature("premium"):
    enable_premium_features()

# Check product
if validator.has_product("analytics"):
    enable_analytics_module()

API Reference

Classe `LicenseValidator`

from quantumlock_sdk import LicenseValidator

Constructor

LicenseValidator(
    license_path: str | None = None,
    online_validation: bool = False,
    api_url: str = "https://quantumlock.softquantus.com",
    api_key: str | None = None
)

Parameter	Tipo	Default	Description
`license_path`	`str \| None`	`None`	Path to `.lic` file (can be passed in `validate()`)
`online_validation`	`bool`	`False`	If `True`, also validates against the API
`api_url`	`str`	`"https://quantumlock.softquantus.com"`	API URL (for online validation)
`api_key`	`str \| None`	`None`	API Key (for online validation)

`validate(license_path=None) → bool`

Validates a license file. Checks:

File existence
JSON structure (required fields)
Expiration date
Quantum signature integrity
Online validation (optional)

validator = LicenseValidator()

# Option A: pass path in validate()
is_valid = validator.validate("/path/to/license.lic")

# Option B: pass path in constructor
validator = LicenseValidator("/path/to/license.lic")
is_valid = validator.validate()

Returns: True if valid, False if invalid.

Raises: LicenseError if the file does not exist or is corrupted.

`has_feature(feature: str) → bool`

Checks if a feature is enabled in the license.

if validator.has_feature("premium_api"):
    # Premium feature available
    pass

Returns: True if the feature is in the license feature list.

Returns False if the license has not been validated or is invalid.

`has_product(product_code: str) → bool`

Checks if a product is licensed. Product codes are included as features in the license.

if validator.has_product("synapsex"):
    # SynapseX product licensed
    pass

if validator.has_product("qcos"):
    # QCOS product licensed
    pass

Product Code	Product
`qcos`	QCOS
`synapsex`	SynapseX
`quantumlock`	QuantumLock
`qsa`	QSA

`require_feature(feature: str)` — Decorator

Decorator that requires a specific feature. Raises FeatureNotLicensed if the feature is not in the license.

validator = LicenseValidator("/path/to/license.lic")
validator.validate()

@validator.require_feature("premium_api")
def premium_endpoint():
    return {"data": "premium content"}

# If "premium_api" is not in the license:
# FeatureNotLicensed: Feature 'premium_api' not licensed.

`require_product(product_code: str)` — Decorator

Decorator that requires a specific product. Raises FeatureNotLicensed if the product is not licensed.

validator = LicenseValidator("/path/to/license.lic")
validator.validate()

@validator.require_product("qcos")
def qcos_only_function():
    return {"data": "qcos exclusive"}

# If "qcos" is not in the license:
# FeatureNotLicensed: Product 'qcos' not licensed.

`get_license_info() → dict`

Returns detailed license information.

info = validator.get_license_info()
print(info)

Retorna:

{
    "customer_id": "customer@company.com",
    "license_key": "QCOS-41FB-639F-...",
    "features": ["premium", "api_access"],
    "valid_until": "2026-06-15T10:30:00",
    "quantum_verified": True,
    "security_level": "Quantum-QCOS-16Q",
    "qcos_fidelity": 0.9847
}

`is_valid() → bool`

Checks if the license was validated successfully (after calling validate()).

if validator.is_valid():
    print("License active")

`get_features() → list[str]`

Returns the list of enabled features.

features = validator.get_features()
# ["premium", "api_access", "analytics"]

Returns [] if the license is invalid.

`get_expiration() → datetime | None`

Returns the license expiration date.

from datetime import datetime

expiration = validator.get_expiration()
if expiration:
    print(f"Expires on: {expiration.isoformat()}")

`days_until_expiration() → int | None`

Returns the number of days until expiration.

days = validator.days_until_expiration()
if days is not None:
    if days < 30:
        print(f"⚠️ License expires in {days} days!")

Exceptions

`LicenseError`

Base exception for license errors.

from quantumlock_sdk import LicenseError

try:
    validator.validate("/path/to/license.lic")
except LicenseError as e:
    print(f"Erro: {e}")

Common messages:

Message	Cause
`"License file not found: /path/..."`	File does not exist
`"License file corrupted: ..."`	Invalid JSON
`"License missing required field: ..."`	Required field missing
`"License missing customer identification field"`	No `customer_id` or `end_customer_id`
`"License validation failed: ..."`	Generic error

`FeatureNotLicensed`

Exception raised by the require_feature() and require_product() decorators.

from quantumlock_sdk import FeatureNotLicensed

try:
    result = premium_endpoint()
except FeatureNotLicensed as e:
    print(f"Access denied: {e}")
    # "Feature 'premium_api' not licensed. Upgrade at https://portal.softquantus.com"

Convenience Functions

`validate_license(license_path: str) → bool`

Quick validation in one line.

from quantumlock_sdk.validator import validate_license

if validate_license("/etc/myapp/license.lic"):
    print("Valid!")

`get_license_info(license_path: str) → dict`

Get license information in one line.

from quantumlock_sdk.validator import get_license_info

info = get_license_info("/etc/myapp/license.lic")
print(f"Customer: {info['customer_id']}")
print(f"Features: {info['features']}")

Integration Examples

Web Application (FastAPI/Flask)

from fastapi import FastAPI, HTTPException
from quantumlock_sdk import LicenseValidator, FeatureNotLicensed

app = FastAPI()

# Initialize and validate license at startup
validator = LicenseValidator("/etc/myapp/license.lic")

if not validator.validate():
    raise RuntimeError("❌ Invalid license! Application cannot start.")

print(f"✓ License valid until {validator.get_expiration()}")
print(f"✓ Features: {validator.get_features()}")


@app.get("/api/data")
def get_data():
    """Endpoint available for all plans."""
    return {"data": "basic content"}


@app.get("/api/analytics")
def get_analytics():
    """Endpoint that requires 'analytics' feature."""
    if not validator.has_feature("analytics"):
        raise HTTPException(403, "Feature 'analytics' not licensed")
    return {"analytics": "premium data"}


# Using decorator
@app.get("/api/premium")
@validator.require_feature("premium_api")
def premium_endpoint():
    return {"premium": "exclusive content"}

CLI Application

import sys
from quantumlock_sdk import LicenseValidator, LicenseError

def main():
    validator = LicenseValidator()

    # Try multiple locations for the license file
    license_paths = [
        "./license.lic",
        "/etc/myapp/license.lic",
        "~/.myapp/license.lic"
    ]

    valid = False
    for path in license_paths:
        try:
            if validator.validate(path):
                valid = True
                break
        except LicenseError:
            continue

    if not valid:
        print("❌ No valid license found!")
        print("   Place your license.lic file in one of:")
        for p in license_paths:
            print(f"     {p}")
        sys.exit(1)

    info = validator.get_license_info()
    print(f"✓ Licensed to: {info['customer_id']}")
    print(f"  Features: {', '.join(info['features'])}")
    print(f"  Expires: {info['valid_until']}")

    days = validator.days_until_expiration()
    if days is not None and days < 30:
        print(f"  ⚠️  License expires in {days} days!")

    # Your application here...

if __name__ == "__main__":
    main()

Online + Offline Validation (Hybrid)

from quantumlock_sdk import LicenseValidator

# Offline validation + online verification when available
validator = LicenseValidator(
    license_path="/etc/myapp/license.lic",
    online_validation=True,
    api_url="https://quantumlock.softquantus.com",
    api_key="qlk_your_api_key"
)

# If the API is unavailable, online validation is skipped
# and local validation is considered sufficient
is_valid = validator.validate()

Multi-Product Protection

from quantumlock_sdk import LicenseValidator

validator = LicenseValidator("/etc/licenses/enterprise.lic")
validator.validate()

# Check which products are licensed
products = ["qcos", "synapsex", "quantumlock", "qsa"]

for product in products:
    status = "✓" if validator.has_product(product) else "✗"
    print(f"  {status} {product}")

# Example output:
#   ✓ qcos
#   ✓ synapsex
#   ✗ quantumlock
#   ✗ qsa

.lic File Format

The .lic file can be:

Plain JSON (readable):

{
  "license_key": "QCOS-41FB-639F-C30B-14E3-6342-7B3E-6426-9320",
  "quantum_signature": "a1b2c3d4e5f6abcdef...(128 hex chars)",
  "customer_id": "customer@company.com",
  "features": ["premium", "api_access"],
  "valid_until": "2026-06-15T10:30:00Z",
  "security_level": "Quantum-QCOS-16Q",
  "qcos_fingerprint": {
    "fidelity": 0.9847
  },
  "final_signature": "sha3_512_hash..."
}

Base64-encoded (for distribution):

JSON content encoded in Base64. The SDK automatically detects the format.

Required fields:

Campo	Description
`license_key`	License key
`quantum_signature`	Quantum signature (128 hex chars)
`valid_until`	Expiration date (ISO 8601)
`customer_id` ou `end_customer_id`	Customer identifier

Optional fields:

Campo	Description
`features`	List of enabled features
`security_level`	Security level
`qcos_fingerprint`	Quantum fingerprint with fidelity
`final_signature`	SHA3-512 for integrity verification

Signature Verification

The SDK validates signatures in two ways:

With final_signature: Recalculates the SHA3-512 of the entire JSON (without the final_signature field) and compares.
Without final_signature: Verifies that quantum_signature is a valid 128-character hex string (SHA3-512).

Troubleshooting

`LicenseError: License file not found`

Check the file path. Use absolute paths.

`LicenseError: License file corrupted`

The file is not valid JSON or Base64-encoded JSON.

`LicenseError: License missing required field`

The .lic file is incomplete. Generate a new license via API/CLI.

Online validation fails

If online_validation=True and the API is unavailable, the SDK accepts local validation. This is intentional — it ensures offline operation.

Expired license

validate() returns False (does not raise an exception). Use days_until_expiration() for proactive alerts.

Overview​

Installation​

Dependencies​

Step-by-Step Guide​

Complete Flow: From generation to validation​

Step 1: Generate a license (API or CLI)​

Passo 2: Converta e distribua o .lic file​

Step 3: Validate in the customer software​

Passo 4: Gate features by license​

API Reference​

Classe LicenseValidator​

Constructor​

validate(license_path=None) → bool​

has_feature(feature: str) → bool​

has_product(product_code: str) → bool​

require_feature(feature: str) — Decorator​

require_product(product_code: str) — Decorator​

get_license_info() → dict​

is_valid() → bool​

get_features() → list[str]​

get_expiration() → datetime | None​

days_until_expiration() → int | None​

Exceptions​

LicenseError​

FeatureNotLicensed​

Convenience Functions​

validate_license(license_path: str) → bool​

get_license_info(license_path: str) → dict​

Integration Examples​

Web Application (FastAPI/Flask)​

CLI Application​

Online + Offline Validation (Hybrid)​

Multi-Product Protection​

.lic File Format​

Signature Verification​

Troubleshooting​

LicenseError: License file not found​

LicenseError: License file corrupted​

LicenseError: License missing required field​

Online validation fails​

Expired license​