Saltar al contenido principal

🔵 SDK Oficial para Golang (Manual Técnico & API de Métodos)

El paquete validlicense es el SDK oficial para Golang. Ha sido diseñado para microservicios concurrentes, daemons de infraestructura, APIs de alto rendimiento y herramientas CLI utilizando el paquete estándar crypto/ed25519 del compilador de Go.

🏛️ 1. Estructuras de Datos (Structs)​

ClientOptions​

Opciones de inicialización del cliente:

type ClientOptions struct {
    ServerURL     string        // URL base del servidor VPS (ej: "https://licencias.labtec.sbs")
    PublicKeyHex  string        // Clave Pública Ed25519 de 32 bytes en formato Hexadecimal (64 caracteres)
    ClientVersion string        // Versión del cliente (por defecto "2026.1")
    HTTPTimeout   time.Duration // Timeout para peticiones de red (por defecto 6 segundos)
}

ValidLicenseRecord​

Estado inmutable retornado tras la verificación:

type ValidLicenseRecord struct {
    IsActive      bool                   `json:"isActive"`      // true si la licencia está vigente y no revocada
    Status        string                 `json:"status"`        // "ACTIVE", "SUSPENDED", "EXPIRED", "REVOKED"
    CompanyName   string                 `json:"companyName"`   // Razón social del cliente
    CompanyNit    string                 `json:"companyNit"`    // NIT tributario
    Plan          string                 `json:"plan"`          // Nombre del plan comercial
    ExpiresAt     string                 `json:"expiresAt"`     // Fecha de expiración ISO 8601
    DaysLeft      int                    `json:"daysLeft"`      // Días restantes
    IsTrial       bool                   `json:"isTrial"`       // Indica si es una licencia de prueba
    MaxUsers      int                    `json:"maxUsers"`      // Límite de usuarios simultáneos
    DianQuota     int                    `json:"dianQuota"`     // Cuota autorizada de facturas electrónicas
    DianUsed      int                    `json:"dianUsed"`      // Facturas electrónicas consumidas
    Features      []string               `json:"features"`      // Lista de módulos contratados
    CustomData    map[string]interface{} `json:"customData"`    // Metadatos personalizados
    ServerMessage string                 `json:"serverMessage"` // Mensaje o motivo de respuesta
    Token         string                 `json:"token"`         // Token criptográfico renovado
}

⚙️ 2. Métodos de ValidLicenseClient​

NewClient(options ClientOptions) *ValidLicenseClient​

Inicializa una nueva instancia del cliente configurando el pool HTTP y normalizando la clave pública.

(c *ValidLicenseClient) GetMachineID() (string, error)​

  • Propósito: Calcula la huella única de hardware del equipo actual en formato REX-XXXX-XXXX-XXXX.
  • Implementación:
    • En Windows: Consulta el registro HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid.
    • En Linux: Lee /etc/machine-id o /var/lib/dbus/machine-id.
    • En macOS: Consulta IOPlatformUUID vía ioreg.
    • Genera una suma SHA-256 dividida en 4 bloques hexadecimales.

(c *ValidLicenseClient) VerifyTokenSignature(token string) bool​

  • Propósito: Valida matemáticamente si la firma digital Ed25519 del token es legítima.
  • Implementación:
    • Decodifica la clave pública hexadecimal a 32 bytes ed25519.PublicKey.
    • Decodifica la firma hexadecimal de 128 caracteres a 64 bytes de firma.
    • Ejecuta ed25519.Verify(pubKey, payloadBytes, signatureBytes).

(c *ValidLicenseClient) Verify(companyNit, currentToken string, customData map[string]interface{}) (*ValidLicenseRecord, error)​

  • Propósito: Ejecuta el ciclo de vida de verificación en 2 fases:
    1. Fase 1 (Online): Realiza un POST a /api/v1/license/verify en el VPS. Si el servidor responde 200 OK, actualiza los datos y renueva el token.
    2. Fase 2 (Fallback Offline): Si no hay conexión, decodifica el currentToken local, valida la firma asimétrica con VerifyTokenSignature y comprueba que la fecha actual sea menor a ExpiresAt.

(r *ValidLicenseRecord) HasFeature(featureName string) bool​

  • Propósito: Retorna true si el módulo solicitado se encuentra dentro de la lista de Features autorizadas en la licencia.

🛡️ 3. Módulo Anti-Tamper en Go​

Funciones a nivel de paquete para fortificar binarios en Go:

  • validlicense.DeriveEncryptionKey(rawToken, salt):
    • Deriva una clave AES-256 a partir de la firma del token para cifrar bases de datos locales o estructuras en memoria.
  • validlicense.VerifyClockIntegrity(lastIso, checksum, runCount, machineId, salt, toleranceMinutes):
    • Verifica que el reloj de Windows o Linux no haya sido retrasado deliberadamente.
  • validlicense.IsDebuggerAttached():
    • Detecta si el binario Go está siendo ejecutado bajo gdb, lldb o inspeccionado por un proceso padre.

🔒 4. Módulo UiGuard (Protección de Vistas en Go)​

Permite proteger vistas HTML, templates o respuestas de endpoints:

// 1. Proteger una vista completa
viewOutput := validlicense.UiGuard{}.GuardView(
    status,
    func() string { return renderDashboardHtml() },  // Solo si es válida
    func() string { return renderLockScreenHtml() }, // Fallback si no está activa
)

// 2. Proteger por Feature Flag
billingView := validlicense.UiGuard{}.GuardFeature(
    status,
    "electronic_billing",
    func() string { return renderFacturacionDian() },
    func() string { return "Módulo no autorizado." },
)

// 3. Proteger páginas React / Vue compiladas
finalHtml := validlicense.UiGuard{}.GuardAsset(status, bundledReactHtml, "")

💻 5. Ejemplo Completo de Integración en Go​

package main

import (
	"fmt"
	"log"
	"os"
	"time"
	"validlicense"
)

func main() {
	// 1. Configurar cliente
	client := validlicense.NewClient(validlicense.ClientOptions{
		ServerURL:    os.Getenv("VALID_LICENSE_SERVER_URL"),
		PublicKeyHex: os.Getenv("ED25519_PUBLIC_KEY"),
		HTTPTimeout:  5 * time.Second,
	})

	// 2. Obtener Machine ID
	machineID, err := client.GetMachineID()
	if err != nil {
		log.Fatalf("❌ Error obteniendo Machine ID: %v", err)
	}
	fmt.Printf("🔒 Hardware ID: %s\n", machineID)

	// 3. Verificar Licencia
	status, err := client.Verify("900.888.777-1", os.Getenv("LICENSE_TOKEN"), map[string]interface{}{
		"tier": "enterprise",
	})

	if err != nil || !status.IsActive {
		log.Fatalf("❌ Acceso Denegado: %v", status.ServerMessage)
	}

	fmt.Printf("✅ Licencia Activa para: %s (Plan: %s)\n", status.CompanyName, status.Plan)
	fmt.Printf("📅 Válida hasta: %s (%d días restantes)\n", status.ExpiresAt, status.DaysLeft)
	fmt.Printf("📑 Cuota DIAN: %d / %d\n", status.DianUsed, status.DianQuota)

	// 4. Validar Feature Flag
	if status.HasFeature("electronic_billing") {
		fmt.Println("⚡ Módulo de Facturación Electrónica Activo")
	}
}