QuantumLock™ - Documentação Técnica Completa
Versão: 2.1.1 Última Atualização: Janeiro 2025 Copyright: SoftQuantus Innovative OÜ
Índice
- Visão Geral
- Instalação
- SDK - Python
- CLI - Command Line Interface
- API REST
- Configuração via Variáveis de Ambiente
- Exemplos de Integração
- Tratamento de Erros
- Melhores Práticas
Visão Geral
QuantumLock™ é um sistema de licenciamento enterprise-grade com criptografia quântica. Oferece três formas de integração:
| Componente | Uso | PyPI |
|---|---|---|
| SDK | Validação de licenças em aplicações Python | pip install quantumlock-sdk |
| CLI | Gerenciamento via linha de comando | pip install quantumlock-cli |
| API | Serviço REST para integrações | https://quantumlock.softquantus.com |
Instalação
SDK (Recommended)
pip install quantumlock-sdk
CLI
pip install quantumlock-cli
Ambos
pip install quantumlock-sdk quantumlock-cli
Verificar Instalação
# CLI
quantumlock version
# SDK (Python)
python -c "from quantumlock_sdk import LicenseValidator; print('OK')"
SDK - Python
Imports Corretos
⚠️ IMPORTANTE: Use imports diretos do pacote raiz. Não importe de submódulos.
# ✅ CORRETO - Import direto
from quantumlock_sdk import LicenseValidator
from quantumlock_sdk import QuantumLockClient
from quantumlock_sdk import LicenseValidatorV2, ValidationResult, ValidationError
# ❌ INCORRETO - Submódulos não são públicos
from quantumlock_sdk.validator import LicenseValidator # NÃO FUNCIONA
from quantumlock_sdk.models import LicenseData # NÃO FUNCIONA
Exports Disponíveis
from quantumlock_sdk import (
# v1 API (Legacy)
LicenseValidator, # Validador básico de licenças
LicenseError, # Erro genérico de licença
FeatureNotLicensed, # Feature não incluída na licença
QuantumLockClient, # Cliente API com criptografia quântica
# v2 API (Recomendado)
LicenseValidatorV2, # Validador v2 com mais recursos
ValidationResult, # Resultado detalhado da validação
ValidationError, # Erro de validação
validate_license, # Função utilitária rápida
)
LicenseValidator (v1)
Validador simples para integração rápida.
Inicialização
from quantumlock_sdk import LicenseValidator
# Opção 1: Caminho para arquivo de licença
validator = LicenseValidator("/path/to/license.qlicense")
# Opção 2: Usar caminho padrão (~/.quantumlock/license.qlicense)
validator = LicenseValidator()
Métodos
# Validar licença
is_valid = validator.validate() # bool
# Validar com path específico
is_valid = validator.validate("/custom/path/license.qlicense")
# Verificar se feature está licenciada
if validator.has_feature("premium_api"):
# Código premium
pass
# Obter features da licença
features = validator.get_features() # List[str]
# Obter informações completas
info = validator.get_info() # Dict
# {
# "license_id": "QLK-...",
# "customer_id": "...",
# "customer_name": "...",
# "features": [...],
# "valid_from": "...",
# "valid_until": "...",
# "quantum_verified": True
# }
Exemplo Completo
from quantumlock_sdk import LicenseValidator, LicenseError, FeatureNotLicensed
try:
validator = LicenseValidator("/app/license.qlicense")
if not validator.validate():
print("Licença inválida!")
exit(1)
print(f"Licença válida para: {validator.get_info()['customer_name']}")
print(f"Features: {validator.get_features()}")
# Gate de feature
if validator.has_feature("enterprise_analytics"):
run_analytics()
else:
print("Feature não disponível no seu plano")
except LicenseError as e:
print(f"Erro de licença: {e}")
except FeatureNotLicensed as e:
print(f"Feature não licenciada: {e}")
LicenseValidatorV2
Validador avançado com suporte a validação online/offline.
from quantumlock_sdk import LicenseValidatorV2, ValidationResult, ValidationError
# Inicialização
validator = LicenseValidatorV2(
license_path="/path/to/license.qlicense", # Opcional
api_url="https://quantumlock.softquantus.com", # Opcional
api_key="qlk_...", # Opcional
)
# Validar
result: ValidationResult = validator.validate()
# Verificar resultado
if result.is_valid:
print(f"Licença válida!")
print(f"Customer: {result.customer_name}")
print(f"Features: {result.features}")
print(f"Expira em: {result.expires_at}")
print(f"Modo: {result.validation_mode}") # "online" ou "offline"
else:
print(f"Licença inválida: {result.message}")
print(f"Status: {result.status}") # LicenseStatus enum
Função Utilitária
from quantumlock_sdk import validate_license
# Validação rápida em uma linha
is_valid = validate_license("/path/to/license.qlicense")
HybridLicenseValidator
Validador híbrido com suporte a modo online/offline, grace period, e sincronização em background.
from quantumlock.sdk.hybrid_validator import (
HybridLicenseValidator,
HybridConfig,
LicenseStatus,
ValidationResult,
)
# Configuração via código
config = HybridConfig(
api_url="https://quantumlock.softquantus.com",
api_key="qlk_...",
license_path="/path/to/license.qlicense",
mode="hybrid", # "online", "offline", "hybrid"
sync_interval_hours=24,
grace_period_days=7,
cache_dir="~/.quantumlock/cache",
require_online_first=False,
telemetry_enabled=True,
)
# Inicialização
validator = HybridLicenseValidator(config=config)
# Ou via variáveis de ambiente
validator = HybridLicenseValidator() # Usa HybridConfig.from_env()
LicenseStatus (Enum)
from quantumlock.sdk.hybrid_validator import LicenseStatus
# Possíveis estados:
LicenseStatus.VALID # Licença válida (online verificada)
LicenseStatus.VALID_OFFLINE # Válida localmente (offline)
LicenseStatus.VALID_GRACE # Em período de graça
LicenseStatus.EXPIRED # Licença expirada
LicenseStatus.REVOKED # Licença revogada
LicenseStatus.INVALID_SIGNATURE # Assinatura inválida
LicenseStatus.NOT_FOUND # Licença não encontrada
LicenseStatus.ERROR # Erro genérico
ValidationResult (Dataclass)
@dataclass
class ValidationResult:
status: LicenseStatus # Estado da licença
is_valid: bool # Resultado simplificado
message: str # Mensagem legível
license_id: str = None # ID da licença
customer_id: str = None # ID do cliente
customer_name: str = None # Nome do cliente
features: List[str] = None # Features ativas
expires_at: datetime = None # Data de expiração
grace_expires_at: datetime = None # Fim do grace period
validation_mode: str = None # "online" ou "offline"
quantum_verified: bool = False # Verificação quântica
metadata: Dict = None # Metadados extras
Métodos
# Carregar licença do arquivo
license_data = validator.load_license()
license_data = validator.load_license("/custom/path.qlicense")
# Validar (retorna ValidationResult)
result = validator.validate()
# Verificar feature
if validator.has_feature("premium"):
# ...
# Callbacks para eventos
validator.on_revoked = lambda result: notify_admin(result)
validator.on_grace_period = lambda result: show_warning(result)
validator.on_online_validated = lambda result: log_validation(result)
# Iniciar sincronização em background
validator.start_background_sync()
# Parar sincronização
validator.stop_background_sync()
QuantumLockClient
Cliente completo para API QuantumLock com operações de criptografia quântica.
Inicialização
from quantumlock_sdk import QuantumLockClient
# Via parâmetros
client = QuantumLockClient(
api_url="https://quantumlock.softquantus.com",
api_key="qlk_...",
)
# Via variáveis de ambiente
# QUANTUMLOCK_API_URL, QUANTUMLOCK_API_KEY
client = QuantumLockClient()
Gerenciamento de Licenças
# Gerar nova licença
license = client.generate_license(
end_customer_id="user@company.com",
features=["premium", "api_access", "analytics"],
expires_in_days=365,
metadata={"department": "Engineering", "seats": 50}
)
print(f"License Key: {license['license_key']}")
print(f"Quantum Fidelity: {license['quantum_fidelity']}")
# Validar licença
result = client.validate_license("QCOS-XXXX-XXXX-XXXX-XXXX")
if result['valid']:
print("Licença válida!")
print(f"Features: {result['features']}")
else:
print(f"Inválida: {result['message']}")
# Listar licenças
licenses = client.list_licenses(
page=1,
per_page=50,
status="active" # "active", "expired", "revoked", "all"
)
# Estatísticas
stats = client.get_stats()
print(f"Licenças este mês: {stats['this_month']}/{stats['monthly_limit']}")
print(f"Fidelidade média: {stats['quantum_fidelity_avg']}")
# Informações do cliente
info = client.get_customer_info()
print(f"Plano: {info['plan']}")
Criptografia Quântica
# Encriptar dados com chave quântica
encrypted = client.quantum_encrypt(
data=b"dados secretos",
algorithm="AES-256-GCM" # Opcional
)
key_id = encrypted['key_id'] # IMPORTANTE: salve para descriptografar!
ciphertext = encrypted['ciphertext']
# Descriptografar
decrypted = client.quantum_decrypt(
ciphertext=ciphertext,
key_id=key_id
)
original_data = decrypted['plaintext']
# Assinar com nonce quântico
signature = client.quantum_sign(
data=b"documento para assinar",
algorithm="ML-DSA-65" # Opcional
)
print(f"Assinatura: {signature['signature']}")
print(f"Quantum Nonce: {signature['quantum_nonce']}")
# Verificar assinatura
is_valid = client.quantum_verify(
data=b"documento para assinar",
signature=signature['signature'],
quantum_nonce=signature['quantum_nonce']
)
# Key Exchange (Kyber)
exchange = client.quantum_key_exchange()
public_key = exchange['public_key']
private_key_id = exchange['private_key_id']
# Obter entropia quântica
entropy = client.quantum_entropy(
bytes_count=32 # Número de bytes
)
random_bytes = entropy['entropy']
# Health check da API
health = client.quantum_health()
print(f"API Status: {health['status']}")
CLI - Command Line Interface
Instalação e Configuração
# Instalar
pip install quantumlock-cli
# Configurar (interativo)
quantumlock configure
# Ou via variáveis de ambiente
export QUANTUMLOCK_API_URL="https://quantumlock.softquantus.com"
export QUANTUMLOCK_API_KEY="qlk_..."
Comandos Disponíveis
quantumlock configure
Configuração interativa da CLI.
quantumlock configure
# Prompts:
# - API URL (default: https://quantumlock.softquantus.com)
# - API Key: qlk_...
quantumlock generate
Gerar nova licença.
quantumlock generate \
--customer "user@company.com" \
--features "premium,api_access,analytics" \
--days 365 \
--metadata "department=Engineering" \
--metadata "seats=50" \
--output license.json
Opções:
| Opção | Abreviação | Descrição | Padrão |
|---|---|---|---|
--customer | -c | ID do cliente final (obrigatório) | - |
--features | -f | Features separadas por vírgula (obrigatório) | - |
--days | -d | Dias de validade | 365 |
--metadata | -m | Metadados (key=value), pode repetir | - |
--output | -o | Salvar em arquivo JSON | - |
quantumlock validate
Validar uma licença.
quantumlock validate QCOS-XXXX-XXXX-XXXX-XXXX
quantumlock stats
Mostrar estatísticas de uso.
quantumlock stats
Output:
Account: company@email.com
Plan: BUSINESS
License Statistics
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Metric ┃ Value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩