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>
123 lines
5.2 KiB
Markdown
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)
|
|
```
|