QuantumLock™ Commercial Integration Guide

Guia Completo para Integração em Produtos Comerciais

Este documento explica como integrar o sistema de licenciamento QuantumLock™ em seus produtos comerciais.

---

📋 Índice

1. Visão Geral
2. Fluxo de Licenciamento
3. Configuração Inicial
4. Integração via SDK Python
5. Integração via CLI
6. Integração via API REST
7. Validação de Licenças
8. Modos de Operação
9. Variáveis de Ambiente
10. Troubleshooting

---

Visão Geral

O QuantumLock™ oferece licenciamento seguro com:

• Assinatura Quântica: Algoritmo QuantumFingerprint-16Q-SHA3-512
• Validação Offline-First: Produto inicia em < 5ms
• Sync em Background: Verifica revogações sem bloquear
• Zero Dependências Externas: Não requer liboqs ou bibliotecas PQC

Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                    SEU PRODUTO COMERCIAL                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────┐     ┌─────────────────────────────────┐  │
│   │  Sua Aplicação  │────▶│  HybridLicenseValidator (SDK)   │  │
│   └─────────────────┘     └───────────────┬─────────────────┘  │
│                                           │                     │
│                           ┌───────────────┴───────────────┐    │
│                           │                               │    │
│                           ▼                               ▼    │
│                  ┌─────────────────┐           ┌──────────────┐│
│                  │ Validação       │           │ Sync         ││
│                  │ Offline (< 5ms) │           │ Background   ││
│                  └─────────────────┘           └──────┬───────┘│
│                                                       │        │
└───────────────────────────────────────────────────────┼────────┘
                                                        │
                                                        ▼
                                           ┌────────────────────┐
                                           │ QuantumLock™ API   │
                                           │ (Revogação/Sync)   │
                                           └────────────────────┘

---

Fluxo de Licenciamento

Para Você (Vendor)

1. Portal Admin: Acesse admin.softquantus.com
2. Crie Licença: Gere licença para seu cliente
3. Entregue: Envie arquivo .qlicense ao cliente

Para Seu Cliente (End-User)

1. Recebe Licença: Arquivo .qlicense do vendor
2. Configura: export QUANTUMLOCK_LICENSE_PATH=/path/to/license.qlicense
3. Usa Produto: Aplicação valida automaticamente

---

Configuração Inicial

1. Instalar SDK

pip install quantumlock-sdk

2. Configurar Licença

# Opção 1: Variável de ambiente
export QUANTUMLOCK_LICENSE_PATH=/etc/myapp/license.qlicense

# Opção 2: Arquivo no diretório padrão
cp license.qlicense ~/.quantumlock/license.qlicense

# Opção 3: Diretório da aplicação
cp license.qlicense ./license.qlicense

3. Configurar API (Opcional - para sync online)

export QUANTUMLOCK_API_URL=https://quantumlock.softquantus.com
export QUANTUMLOCK_API_KEY=ql_your_api_key

---

Integração via SDK Python

Uso Básico

from quantumlock.sdk import HybridLicenseValidator

# Criar validador (carrega config de ambiente)
validator = HybridLicenseValidator()

# Validar licença (< 5ms)
result = validator.validate()

if result.is_valid:
    print(f"✅ Licença válida!")
    print(f"   Cliente: {result.customer_name}")
    print(f"   Features: {result.features}")
    print(f"   Expira: {result.expires_at}")

    # Iniciar aplicação
    run_my_application()
else:
    print(f"❌ Licença inválida: {result.message}")
    show_purchase_dialog()

Com Context Manager

from quantumlock.sdk import HybridLicenseValidator, LicenseError

try:
    with HybridLicenseValidator() as validator:
        # Licença validada automaticamente
        # Sync em background iniciado
        run_my_application()

except LicenseError as e:
    print(f"Erro de licença: {e}")
    sys.exit(1)

Proteger Funções com Decorator

from quantumlock.sdk import HybridLicenseValidator

validator = HybridLicenseValidator()

@validator.require_license(features=["premium"])
def premium_feature():
    """Só executa se licença tem feature 'premium'"""
    return expensive_computation()

@validator.require_license(features=["analytics", "export"])
def export_analytics():
    """Requer múltiplas features"""
    return generate_report()

# Uso
result = premium_feature()  # Valida licença antes de executar

Verificar Features Específicas

validator = HybridLicenseValidator()
result = validator.validate()

if result.is_valid:
    # Verificar features individuais
    if validator.has_feature("premium"):
        enable_premium_ui()

    if validator.has_feature("api"):
        enable_api_access()

    if validator.has_feature("unlimited_users"):
        remove_user_limit()
    else:
        set_user_limit(10)  # Limite para plano básico

Callbacks para Eventos

from quantumlock.sdk import HybridLicenseValidator, ValidationResult

validator = HybridLicenseValidator()

# Quando licença é revogada remotamente
@validator.on_revoked
def handle_revocation(result: ValidationResult):
    print(f"⚠️ Licença revogada: {result.message}")
    show_license_revoked_dialog()
    disable_premium_features()
    # Opcional: forçar logout ou modo demo

# Quando entra em grace period (sem conexão por muito tempo)
@validator.on_grace_period
def handle_grace_period(result: ValidationResult):
    print(f"⚠️ Grace period até {result.grace_period_ends}")
    show_reconnect_warning()

# Iniciar validação
result = validator.validate()

Integração com FastAPI

from fastapi import FastAPI, Depends, HTTPException
from quantumlock.sdk import HybridLicenseValidator

app = FastAPI()
validator = HybridLicenseValidator()

@app.on_event("startup")
async def startup():
    result = validator.validate()
    if not result.is_valid:
        raise RuntimeError(f"Licença inválida: {result.message}")

def require_feature(feature: str):
    def check():
        if not validator.has_feature(feature):
            raise HTTPException(403, f"Feature '{feature}' não licenciada")
    return Depends(check)

@app.get("/api/free")
def free_endpoint():
    return {"tier": "free"}

@app.get("/api/premium", dependencies=[require_feature("premium")])
def premium_endpoint():
    return {"tier": "premium", "data": "exclusive content"}

@app.get("/api/analytics", dependencies=[require_feature("analytics")])
def analytics_endpoint():
    return {"analytics": get_analytics_data()}

Integração com Django

# settings.py
from quantumlock.sdk import HybridLicenseValidator

QUANTUMLOCK_VALIDATOR = HybridLicenseValidator()
result = QUANTUMLOCK_VALIDATOR.validate()

if not result.is_valid:
    raise RuntimeError(f"Licença inválida: {result.message}")

# middleware.py
from django.conf import settings
from django.http import HttpResponseForbidden

class LicenseMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # Revalidar periodicamente
        if not settings.QUANTUMLOCK_VALIDATOR.is_valid():
            return HttpResponseForbidden("Licença expirada")
        return self.get_response(request)

# views.py
from django.conf import settings
from functools import wraps

def require_feature(feature: str):
    def decorator(view_func):
        @wraps(view_func)
        def wrapper(request, *args, **kwargs):
            if not settings.QUANTUMLOCK_VALIDATOR.has_feature(feature):
                return HttpResponseForbidden(f"Feature '{feature}' não licenciada")
            return view_func(request, *args, **kwargs)
        return wrapper
    return decorator

@require_feature("analytics")
def analytics_view(request):
    return JsonResponse({"analytics": "data"})

---

Integração via CLI

Instalação

# Download binário
curl -L -o quantumlock https://releases.softquantus.com/cli/quantumlock-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)
chmod +x quantumlock
sudo mv quantumlock /usr/local/bin/

Configurar

# Configurar API key
quantumlock configure --api-key ql_your_api_key

# Ou via variável de ambiente
export QUANTUMLOCK_API_KEY=ql_your_api_key

Validar Licença

# Validar arquivo de licença
quantumlock validate --file /path/to/license.qlicense

# Validar com output JSON
quantumlock validate --file license.qlicense --json

# Validar e mostrar features
quantumlock validate --file license.qlicense --features

Gerar Licença (Para Vendors)

# Gerar licença para cliente
quantumlock generate \
    --customer "ACME Corp" \
    --customer-id "acme-001" \
    --product "MyApp Pro" \
    --features "premium,api,analytics" \
    --days 365 \
    --output acme-license.qlicense

# Listar licenças geradas
quantumlock list --limit 10

# Revogar licença
quantumlock revoke --license-id "lic-abc123"

Scripts de Automação

#!/bin/bash
# check_license.sh - Verificar licença antes de iniciar aplicação

if ! quantumlock validate --file /etc/myapp/license.qlicense --quiet; then
    echo "❌ Licença inválida ou expirada"
    exit 1
fi

echo "✅ Licença válida"
exec /opt/myapp/start.sh

---

Integração via API REST

Autenticação

# Header de autenticação
Authorization: Bearer ql_your_api_key

Endpoints Principais

Validar Licença

POST /api/v1/licenses/validate/hybrid
Content-Type: application/json

{
    "license_id": "lic-abc123",
    "customer_id": "cust-xyz",
    "signature": "base64_signature..."
}

Resposta:

{
    "valid": true,
    "license_id": "lic-abc123",
    "customer_name": "ACME Corp",
    "features": ["premium", "api", "analytics"],
    "expires_at": "2026-12-30T00:00:00Z",
    "quantum_verified": true,
    "revoked": false
}

Criar Licença (Vendors)

POST /api/v1/licenses/create
Content-Type: application/json
Authorization: Bearer ql_your_api_key

{
    "customer_id": "acme-001",
    "customer_name": "ACME Corporation",
    "product": "MyApp Pro",
    "features": ["premium", "api", "analytics"],
    "valid_days": 365,
    "metadata": {
        "tier": "enterprise",
        "seats": 50
    }
}

Resposta:

{
    "license_id": "lic-abc123xyz",
    "customer_id": "acme-001",
    "customer_name": "ACME Corporation",
    "product": "MyApp Pro",
    "features": ["premium", "api", "analytics"],
    "valid_from": "2025-12-30T00:00:00Z",
    "valid_until": "2026-12-30T00:00:00Z",
    "signature": "base64_quantum_signature...",
    "quantum_signature": "base64_quantum_fingerprint...",
    "download_url": "https://quantumlock.softquantus.com/licenses/lic-abc123xyz/download"
}

Listar Revogações

GET /api/v1/revocations/list
Authorization: Bearer ql_your_api_key

Resposta:

{
    "revoked_license_ids": ["lic-revoked-1", "lic-revoked-2"],
    "updated_at": "2025-12-30T15:00:00Z"
}

Revogar Licença

POST /api/v1/licenses/{license_id}/revoke
Authorization: Bearer ql_your_api_key

{
    "reason": "Violação dos termos de uso"
}

Exemplo cURL Completo

# Criar licença
curl -X POST "https://quantumlock.softquantus.com/api/v1/licenses/create" \
  -H "Authorization: Bearer ql_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "acme-001",
    "customer_name": "ACME Corp",
    "product": "MyApp",
    "features": ["premium"],
    "valid_days": 365
  }'

# Validar licença
curl -X POST "https://quantumlock.softquantus.com/api/v1/licenses/validate/hybrid" \
  -H "Content-Type: application/json" \
  -d '{
    "license_id": "lic-abc123",
    "customer_id": "acme-001"
  }'

Exemplo Node.js

const axios = require('axios');

const QUANTUMLOCK_API = 'https://quantumlock.softquantus.com';
const API_KEY = process.env.QUANTUMLOCK_API_KEY;

async function validateLicense(licenseId, customerId) {
    const response = await axios.post(
        `${QUANTUMLOCK_API}/api/v1/licenses/validate/hybrid`,
        { license_id: licenseId, customer_id: customerId },
        { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    return response.data;
}

async function createLicense(customerData) {
    const response = await axios.post(
        `${QUANTUMLOCK_API}/api/v1/licenses/create`,
        customerData,
        { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    return response.data;
}

// Uso
const result = await validateLicense('lic-abc123', 'acme-001');
if (result.valid) {
    console.log('✅ License valid!');
    console.log(`Features: ${result.features.join(', ')}`);
}

---

Validação de Licenças

Estrutura do Arquivo .qlicense

{
    "license_id": "lic-abc123xyz",
    "customer_id": "acme-001",
    "customer_name": "ACME Corporation",
    "product": "MyApp Pro",
    "features": ["premium", "api", "analytics"],
    "issued_at": "2025-12-30T00:00:00Z",
    "valid_from": "2025-12-30T00:00:00Z",
    "valid_until": "2026-12-30T00:00:00Z",
    "signature": "base64_encoded_signature...",
    "quantum_signature": "base64_quantum_fingerprint...",
    "metadata": {
        "tier": "enterprise",
        "seats": 50,
        "algorithm": "QuantumFingerprint-16Q-SHA3-512"
    }
}

O que é Validado

Verificação	Offline	Online
Assinatura criptográfica	✅	✅
Data de expiração	✅	✅
Data de início	✅	✅
Cache de revogação local	✅	✅
Revogação em tempo real	❌	✅
Telemetria	❌	✅

Estados de Licença

Status	Código	Descrição
valid	✅	Licença válida (online verificado)
valid_offline	✅	Válida (apenas verificação local)
valid_grace	⚠️	Válida em grace period
expired	❌	Licença expirada
revoked	❌	Licença revogada
invalid_signature	❌	Assinatura corrompida
not_found	❌	Arquivo não encontrado

---

Modos de Operação

Modo Híbrido (Recomendado)

export QUANTUMLOCK_MODE=hybrid

• Validação offline instantânea (< 5ms)
• Sync de revogação em background
• Grace period de 7 dias sem internet

Modo Offline

export QUANTUMLOCK_MODE=offline

• Apenas validação local
• Sem conexão à API
• Não detecta revogações remotas

Modo Online

export QUANTUMLOCK_MODE=online

• Sempre valida com servidor
• Falha se sem conexão
• Máxima segurança contra pirataria

---

Variáveis de Ambiente

Variável	Tipo	Default	Descrição
QUANTUMLOCK_LICENSE_PATH	string	license.qlicense	Caminho do arquivo de licença
QUANTUMLOCK_MODE	string	hybrid	Modo: offline, online, hybrid
QUANTUMLOCK_API_URL	string	https://quantumlock.softquantus.com	URL da API
QUANTUMLOCK_API_KEY	string	-	Chave de API
QUANTUMLOCK_SYNC_HOURS	int	24	Intervalo de sync (horas)
QUANTUMLOCK_GRACE_DAYS	int	7	Período de graça (dias)
QUANTUMLOCK_API_TIMEOUT	float	5.0	Timeout da API (segundos)
QUANTUMLOCK_CACHE_DIR	string	/var/lib/quantumlock	Diretório de cache
QUANTUMLOCK_REQUIRE_ONLINE	bool	false	Exigir validação online
QUANTUMLOCK_TELEMETRY	bool	true	Habilitar telemetria

---

Troubleshooting

Erro: "Arquivo de licença não encontrado"

LicenseStatus.NOT_FOUND

Solução:

# Verificar se arquivo existe
ls -la $QUANTUMLOCK_LICENSE_PATH

# Definir caminho correto
export QUANTUMLOCK_LICENSE_PATH=/path/to/license.qlicense

Erro: "Assinatura inválida"

LicenseStatus.INVALID_SIGNATURE

Causas:

• Arquivo corrompido durante transferência
• Licença foi modificada manualmente
• Chaves de assinatura diferentes

Solução:

• Baixe o arquivo novamente do Portal
• Verifique integridade: sha256sum license.qlicense

Erro: "Licença expirada"

LicenseStatus.EXPIRED

Solução:

• Contate o vendor para renovação
• Verifique data do sistema: date

Erro: "Licença revogada"

LicenseStatus.REVOKED

Causas:

• Violação dos termos de uso
• Licença substituída por nova
• Solicitação do cliente

Solução:

• Contate o vendor para esclarecimentos

Grace Period

LicenseStatus.VALID_GRACE

Significado:

• Licença válida, mas sem conexão há muito tempo
• Produto continua funcionando
• Conecte à internet antes do fim do grace period

Verificar:

result = validator.validate()
if result.status == LicenseStatus.VALID_GRACE:
    print(f"Grace period até: {result.grace_period_ends}")

---

Suporte

• Email: support@softquantus.com
• Portal: https://portal.softquantus.com
• Documentação: https://docs.softquantus.com
• Status: https://status.softquantus.com

---

Changelog

Versão	Data	Mudanças
2.0.0	2025-12-30	Quantum Fingerprint, HybridLicenseValidator
1.5.0	2025-06-01	Validação offline, grace period
1.0.0	2025-01-01	Release inicial

---

© 2025 SoftQuantus. Todos os direitos reservados.