license-client/README.md
Leonardo Biasoli 75d724291b feat: fingerprint para apps desktop/locais (sem dominio publico)
Adiciona getMachineId()/getDesktopFingerprint() (MachineGuid no
Windows, IOPlatformUUID no macOS, /etc/machine-id no Linux) e a opcao
platform: "desktop" no checkLicense, para apps como AlugaFacil e
ERPbar onde o fingerprint por MAC (platform: "server", default,
inalterado) e instavel — MAC muda entre boots num notebook e gera
FINGERPRINT_MISMATCH falso em cliente legitimo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-15 11:22:36 -03:00

5.2 KiB

@ledcloud/license-client

SDK privado para travar qualquer app da Suite (ou produto licenciado, como Omnilink/ERPbar) ao license-server. Trava por MAC do servidor + domínio: o fingerprint é recalculado a cada validação, então clonar o app inteiro (banco incluso) para outro servidor não copia uma licença válida — o license-server rejeita por FINGERPRINT_MISMATCH.

Instalação

No package.json do app:

"dependencies": {
  "@ledcloud/license-client": "git+https://git.ledcloud.com.br/LED_Cloud/license-client.git"
}

Passo a passo para licenciar um novo app

  1. Cadastre o produto no painel do license-server (/products), com um slug único (ex.: ledcloud-core).

  2. Emita uma licença para cada instância/cliente (/licenses/new), ligada a esse produto.

  3. No app, adicione um model de binding no schema.prisma (singleton, uma linha só):

    model LicenseBinding {
      id            String    @id @default("singleton")
      licenseKey    String
      fingerprint   String
      domain        String
      status        String
      token         String?
      expiresAt     DateTime?
      lastCheckedAt DateTime
    }
    
  4. Implemente o LicenseStore (adaptador fino sobre o Prisma do próprio app):

    import { db } from "@/lib/db";
    import type { LicenseStore } from "@ledcloud/license-client";
    
    export const licenseStore: LicenseStore = {
      async get() {
        const row = await db.licenseBinding.findUnique({ where: { id: "singleton" } });
        return row ?? null;
      },
      async set(data) {
        await db.licenseBinding.upsert({ where: { id: "singleton" }, update: data, create: { id: "singleton", ...data } });
      },
    };
    
  5. Chame checkLicense (middleware, layout raiz, ou um guard de servidor) a cada request (ou com cache curto de alguns minutos — evite chamar em toda request sem cache em produção):

    import { checkLicense } from "@ledcloud/license-client";
    import { licenseStore } from "@/lib/license-store";
    
    const result = await checkLicense(process.env.LICENSE_KEY, {
      licenseServerUrl: "https://licenciamento.ledcloud.com.br",
      product: "ledcloud-core",
      domain: "ledcloud.com.br", // dominio publico desta instancia
      store: licenseStore,
      graceHours: 72, // tolerancia se o license-server ficar fora do ar
    });
    
    if (!result.ok) {
      // renderize uma tela de bloqueio/alerta com result.reason:
      // "NO_LICENSE" | "FINGERPRINT_MISMATCH" | "UNREACHABLE_EXPIRED" | "LICENSE_SUSPENDED" | "LICENSE_EXPIRED" | ...
    }
    

Apps desktop/locais (sem domínio público) — ex.: AlugaFácil, ERPbar

Para apps instalados localmente (Electron, desktop, on-premise sem domínio público), o fingerprint por MAC do getServerFingerprint é instável: o MAC pode mudar entre boots (troca de adaptador, VPN, docking station), gerando FINGERPRINT_MISMATCH falso num cliente legítimo, não numa cópia pirata. Use platform: "desktop" em vez disso — o fingerprint passa a usar um id estável do próprio SO:

  • Windows: MachineGuid do registro.
  • macOS: IOPlatformUUID.
  • Linux: /etc/machine-id (systemd) ou /var/lib/dbus/machine-id.
const result = await checkLicense(licenseKeyDigitadaNaAtivacao, {
  licenseServerUrl: "https://licenciamento.ledcloud.com.br",
  product: "alugafacil", // slug cadastrado no license-server
  domain: installId,     // identificador sintetico da instalacao (UUID gerado na ativacao e
                          // persistido localmente) — NUNCA derivado de hardware aqui; o id do
                          // hardware ja entra pelo lado do fingerprint via platform: "desktop"
  store: licenseStore,
  graceHours: 24 * 14,   // apps locais ficam offline por mais tempo; ajuste a tolerancia
  platform: "desktop",
});

Limitação a aceitar conscientemente: nenhum id de SO é infalível — reinstalar o Windows/macOS troca o MachineGuid/IOPlatformUUID; clonar uma VM/imagem pode duplicá-lo. Isso não é um bug do SDK, é a natureza de identificar hardware em software. Se nenhum id de SO for encontrado (getMachineId() retorna null), o fingerprint cai num valor fixo — nesse caso a única proteção real contra clonagem fica a cargo do domain (o installId persistido pelo app), que por si só não impede copiar a pasta de instalação inteira para outra máquina. Se isso for inaceitável para o produto, fale com o time do license-server sobre alternativas (ex.: ativação online obrigatória com limite de instalações simultâneas por licença, em vez de só fingerprint local).

Motivos de falha (result.reason)

Motivo Significado
NO_LICENSE Nenhuma chave configurada ainda (1º boot da instalação).
FINGERPRINT_MISMATCH O binding salvo no banco local é de outro servidor (app+banco clonados).
UNREACHABLE_EXPIRED license-server fora do ar e o último binding bom já passou do graceHours.
LICENSE_SUSPENDED / LICENSE_EXPIRED / DOMAIN_MISMATCH / ... Devolvidos pelo license-server (ver src/lib/license-service.ts no repo license-server).

Build

npm install
npm run build   # gera dist/, tambem roda automaticamente no "prepare" (npm install via git)