Skip to main content

QuantumLock™ - Documentação Técnica Completa

Versão: 2.1.1 Última Atualização: Janeiro 2025 Copyright: SoftQuantus Innovative OÜ


Índice

  1. Visão Geral
  2. Instalação
  3. SDK - Python
  4. CLI - Command Line Interface
  5. API REST
  6. Configuração via Variáveis de Ambiente
  7. Exemplos de Integração
  8. Tratamento de Erros
  9. Melhores Práticas

Visão Geral

QuantumLock™ é um sistema de licenciamento enterprise-grade com criptografia quântica. Oferece três formas de integração:

ComponenteUsoPyPI
SDKValidação de licenças em aplicações Pythonpip install quantumlock-sdk
CLIGerenciamento via linha de comandopip install quantumlock-cli
APIServiço REST para integraçõeshttps://quantumlock.softquantus.com

Instalação

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çãoAbreviaçãoDescriçãoPadrão
--customer-cID do cliente final (obrigatório)-
--features-fFeatures separadas por vírgula (obrigatório)-
--days-dDias de validade365
--metadata-mMetadados (key=value), pode repetir-
--output-oSalvar 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 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ Total Licenses │ 1234 │
│ Active Licenses │ 1100 │
│ Expired Licenses │ 134 │
│ This Month │ 45/1000 │
│ Usage │ 4.5% │
│ Avg Quantum Fidelity │ 0.9876 │
│ Avg Generation Time │ 23ms │
└───────────────────────┴─────────┘

quantumlock info

Informações da conta.

quantumlock info

quantumlock version

Versão e configuração atual.

quantumlock version
# Output:
# QuantumLock™ CLI
# Version: 2.1.1
# API URL: https://quantumlock.softquantus.com
# Config: ~/.config/quantumlock/config.json
# API Key: configured

Informações legais e de licenciamento.

quantumlock legal

quantumlock v2

Comandos v2 (avançados).

quantumlock v2 --help

API REST

Base URL

Produção: https://quantumlock.softquantus.com

Autenticação

# Via header
X-API-Key: qlk_your_api_key

Endpoints

GET /

Informações do serviço.

curl https://quantumlock.softquantus.com/

Response:

{
"service": "QuantumLock™ API",
"tagline": "Quantum-powered licensing as a service",
"version": "1.0.0",
"docs": "/docs",
"powered_by": "SoftQuantus + QCOS Autopilot"
}

GET /health

Health check.

curl https://quantumlock.softquantus.com/health

Response:

{
"status": "healthy",
"service": "QuantumLock API",
"qcos_available": true,
"timestamp": "2025-01-15T10:30:00Z"
}

POST /api/v1/licenses/generate

Gerar licença quântica.

curl -X POST \
https://quantumlock.softquantus.com/api/v1/licenses/generate \
-H "X-API-Key: qlk_..." \
-H "Content-Type: application/json" \
-d '{
"end_customer_id": "user@company.com",
"features": ["premium", "api_access"],
"valid_days": 365,
"metadata": {"department": "Engineering"}
}'

Request Body:

CampoTipoDescriçãoObrigatório
end_customer_idstringID do cliente final
featuresstring[]Lista de features
valid_daysintegerDias de validade (1-3650)❌ (default: 365)
metadataobjectMetadados customizados

Response:

{
"license_key": "QCOS-41FB-639F-C30B-14E3",
"quantum_signature": "sha3_512_hash...",
"end_customer_id": "user@company.com",
"features": ["premium", "api_access"],
"valid_until": "2026-01-15T00:00:00Z",
"quantum_verified": true,
"qcos_fidelity": 0.9876,
"security_level": "high",
"generated_at": "2025-01-15T10:30:00Z"
}

POST /api/v1/licenses/validate

Validar licença.

curl -X POST \
https://quantumlock.softquantus.com/api/v1/licenses/validate \
-H "X-API-Key: qlk_..." \
-H "Content-Type: application/json" \
-d '{
"license_key": "QCOS-41FB-639F-C30B-14E3",
"end_customer_id": "user@company.com"
}'

Response:

{
"valid": true,
"end_customer_id": "user@company.com",
"quantum_verified": true,
"message": "License valid"
}

GET /api/v1/stats

Estatísticas de uso.

curl https://quantumlock.softquantus.com/api/v1/stats \
-H "X-API-Key: qlk_..."

Response:

{
"licenses_generated_month": 45,
"licenses_remaining_month": 955,
"plan": "business",
"max_licenses_month": 1000
}

GET /api/v1/plans

Planos disponíveis.

curl https://quantumlock.softquantus.com/api/v1/plans

Response:

[
{
"name": "Free",
"price_monthly": "$0",
"licenses_per_month": 100,
"features": ["Basic quantum security", "Email support"]
},
{
"name": "Startup",
"price_monthly": "$99",
"licenses_per_month": 10000,
"features": ["Quantum security", "API access", "Priority support"]
},
{
"name": "Business",
"price_monthly": "$499",
"licenses_per_month": 100000,
"features": ["Advanced quantum", "SLA 99.9%", "24/7 support"]
},
{
"name": "Enterprise",
"price_monthly": "Custom",
"licenses_per_month": 999999999,
"features": ["Unlimited", "Dedicated support", "On-premise option"]
}
]

GET /docs

Documentação OpenAPI interativa (Swagger UI).


Configuração via Variáveis de Ambiente

Todas as Variáveis Suportadas

# === API Configuration ===
QUANTUMLOCK_API_URL="https://quantumlock.softquantus.com"
QUANTUMLOCK_API_KEY="qlk_your_api_key"

# === License Configuration ===
QUANTUMLOCK_LICENSE_PATH="/path/to/license.qlicense"
QUANTUMLOCK_MODE="hybrid" # "online", "offline", "hybrid"

# === Sync & Cache ===
QUANTUMLOCK_SYNC_HOURS="24" # Intervalo de sincronização (horas)
QUANTUMLOCK_GRACE_DAYS="7" # Período de graça (dias)
QUANTUMLOCK_CACHE_DIR="~/.quantumlock/cache"

# === Behavior ===
QUANTUMLOCK_REQUIRE_ONLINE="false" # Requer validação online inicial
QUANTUMLOCK_TELEMETRY="true" # Enviar telemetria anônima

# === Timeouts ===
QUANTUMLOCK_API_TIMEOUT="10" # Timeout da API (segundos)

# === Debug ===
QUANTUMLOCK_DEBUG="false" # Modo debug

Exemplo de Arquivo .env

# .env
QUANTUMLOCK_API_URL=https://quantumlock.softquantus.com
QUANTUMLOCK_API_KEY=qlk_abc123xyz456
QUANTUMLOCK_LICENSE_PATH=/app/config/license.qlicense
QUANTUMLOCK_MODE=hybrid
QUANTUMLOCK_SYNC_HOURS=12
QUANTUMLOCK_GRACE_DAYS=7

Exemplos de Integração

1. Aplicação Simples

#!/usr/bin/env python3
"""Exemplo: Validação simples na inicialização."""

from quantumlock_sdk import LicenseValidator, LicenseError

def main():
try:
validator = LicenseValidator()

if not validator.validate():
print("❌ Licença inválida. Contate o suporte.")
return 1

info = validator.get_info()
print(f"✅ Licença válida para: {info['customer_name']}")
print(f" Expira em: {info['valid_until']}")

# Sua aplicação aqui...
run_application()
return 0

except LicenseError as e:
print(f"❌ Erro de licença: {e}")
return 1

if __name__ == "__main__":
exit(main())

2. Feature Gates

"""Exemplo: Habilitar features baseado na licença."""

from quantumlock_sdk import LicenseValidator

validator = LicenseValidator("/app/license.qlicense")
validator.validate()

# Feature gates
FEATURES = {
"basic": True, # Sempre disponível
"premium_analytics": validator.has_feature("analytics"),
"enterprise_api": validator.has_feature("enterprise_api"),
"white_label": validator.has_feature("white_label"),
}

def run_analytics():
if not FEATURES["premium_analytics"]:
raise FeatureNotAvailable("Analytics requer plano Premium")
# ... implementação

3. Aplicação Web (FastAPI)

"""Exemplo: Middleware de validação para FastAPI."""

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

app = FastAPI()
validator = LicenseValidator()

def validate_license():
"""Dependency para validar licença."""
if not validator.validate():
raise HTTPException(
status_code=403,
detail="Licença inválida ou expirada"
)
return validator

@app.get("/")
def root(license: LicenseValidator = Depends(validate_license)):
return {"status": "ok", "customer": license.get_info()["customer_name"]}

@app.get("/premium")
def premium_endpoint(license: LicenseValidator = Depends(validate_license)):
if not license.has_feature("premium_api"):
raise HTTPException(403, "Feature não disponível no seu plano")
return {"data": "premium content"}

4. Validação Híbrida com Fallback

"""Exemplo: Validação híbrida com grace period."""

import os
from quantumlock.sdk.hybrid_validator import (
HybridLicenseValidator,
HybridConfig,
LicenseStatus
)

# Configuração
config = HybridConfig(
api_url=os.getenv("QUANTUMLOCK_API_URL"),
api_key=os.getenv("QUANTUMLOCK_API_KEY"),
mode="hybrid",
grace_period_days=7,
)

validator = HybridLicenseValidator(config)

# Callbacks
def on_grace_period(result):
print(f"⚠️ AVISO: Licença em período de graça até {result.grace_expires_at}")
send_notification_to_admin()

def on_revoked(result):
print(f"🚫 Licença revogada: {result.message}")
shutdown_application()

validator.on_grace_period = on_grace_period
validator.on_revoked = on_revoked

# Validar
result = validator.validate()

if result.is_valid:
if result.status == LicenseStatus.VALID_GRACE:
print("Funcionando em modo grace period")
elif result.status == LicenseStatus.VALID_OFFLINE:
print("Funcionando em modo offline")
else:
print("Licença totalmente válida")
else:
print(f"Licença inválida: {result.status.name}")
exit(1)

# Iniciar sincronização em background
validator.start_background_sync()

5. Criptografia Quântica

"""Exemplo: Usar criptografia quântica da API."""

from quantumlock_sdk import QuantumLockClient

client = QuantumLockClient()

# Dados sensíveis
sensitive_data = b"dados ultra secretos"

# Encriptar com chave quântica
encrypted = client.quantum_encrypt(sensitive_data)
print(f"Encrypted: {encrypted['ciphertext'][:50]}...")
print(f"Key ID: {encrypted['key_id']}")

# Salvar key_id em local seguro!
# Sem ele, dados não podem ser recuperados

# Mais tarde: descriptografar
decrypted = client.quantum_decrypt(
ciphertext=encrypted['ciphertext'],
key_id=encrypted['key_id']
)
assert decrypted['plaintext'] == sensitive_data

# Assinatura quântica
document = b"contrato importante"
sig = client.quantum_sign(document)

# Verificar em outro sistema
is_authentic = client.quantum_verify(
data=document,
signature=sig['signature'],
quantum_nonce=sig['quantum_nonce']
)
print(f"Documento autêntico: {is_authentic}")

6. Docker Integration

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Instalar SDK
RUN pip install quantumlock-sdk

# Copiar licença (em produção, use secrets)
COPY license.qlicense /app/license.qlicense

# Configurar via env
ENV QUANTUMLOCK_LICENSE_PATH=/app/license.qlicense
ENV QUANTUMLOCK_MODE=hybrid

COPY app.py /app/
CMD ["python", "app.py"]
# docker-compose.yml
services:
app:
build: .
environment:
- QUANTUMLOCK_API_URL=https://quantumlock.softquantus.com
- QUANTUMLOCK_API_KEY=${QUANTUMLOCK_API_KEY}
- QUANTUMLOCK_LICENSE_PATH=/run/secrets/license
secrets:
- license

secrets:
license:
file: ./license.qlicense

Tratamento de Erros

Exceções do SDK

from quantumlock_sdk import (
LicenseValidator,
LicenseError, # Erro base
FeatureNotLicensed, # Feature não disponível
ValidationError, # Erro na validação
)

try:
validator = LicenseValidator()
validator.validate()

# Isso lança FeatureNotLicensed se não tiver a feature
validator.require_feature("enterprise")

except FeatureNotLicensed as e:
print(f"Feature requerida não está na licença: {e}")
print("Upgrade seu plano em: https://portal.softquantus.com")

except ValidationError as e:
print(f"Erro validando licença: {e}")

except LicenseError as e:
print(f"Erro geral de licença: {e}")

Códigos HTTP da API

CódigoDescrição
200Sucesso
201Licença criada
400Request inválido
401API key inválida
403Acesso negado
404Recurso não encontrado
429Rate limit excedido
500Erro interno

Melhores Práticas

✅ Recomendações

  1. Use variáveis de ambiente para configurações sensíveis
  2. Valide na inicialização da aplicação
  3. Use feature gates em vez de if/else espalhados
  4. Configure grace period para evitar interrupções
  5. Implemente callbacks para eventos importantes
  6. Use modo híbrido para melhor resiliência
  7. Salve key_id ao usar criptografia quântica
  8. Monitore fidelidade quântica nas métricas

❌ Evite

  1. Hardcode de API keys no código
  2. Validação em cada request (muito overhead)
  3. Ignorar erros de licença silenciosamente
  4. Cache infinito de validações
  5. Expor API key em logs ou frontend

Segurança

# Bom: variável de ambiente
api_key = os.getenv("QUANTUMLOCK_API_KEY")

# Ruim: hardcoded
api_key = "qlk_secret_key" # NUNCA faça isso!

# Bom: verificar resultado
if not result.is_valid:
raise SystemExit("Licença inválida")

# Ruim: ignorar
result = validator.validate() # e ignorar...

Suporte


© 2025 SoftQuantus Innovative OÜ. Todos os direitos reservados.