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

123 lines
5.2 KiB
Markdown

# @ledcloud/license-client
SDK privado para travar qualquer app da Suite (ou produto licenciado, como Omnilink/ERPbar) ao
[license-server](https://git.ledcloud.com.br/LED_Cloud/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:
```json
"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ó):
```prisma
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):
```ts
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):
```ts
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`.
```ts
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
```bash
npm install
npm run build # gera dist/, tambem roda automaticamente no "prepare" (npm install via git)
```