license-client/README.md
Leonardo Biasoli 0afaf1c38e feat: scaffold inicial do SDK de licenciamento
Fingerprint do servidor (MAC + dominio), validacao contra o
license-server e checkLicense() com binding em banco (via LicenseStore,
adaptador fino que cada app implementa com seu proprio Prisma) e
tolerancia de grace period para indisponibilidade do license-server.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-11 14:50:26 -03:00

89 lines
3.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" | ...
}
```
## 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)
```