diff --git a/README.md b/README.md index 7212f55..da03137 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,40 @@ No `package.json` do app: } ``` +## 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 | diff --git a/src/guard.ts b/src/guard.ts index 99b6d7b..288bdc4 100644 --- a/src/guard.ts +++ b/src/guard.ts @@ -1,4 +1,5 @@ import { getServerFingerprint } from "./fingerprint"; +import { getDesktopFingerprint } from "./machine-id"; import { validateAgainstServer } from "./validate"; export type LicenseBindingRecord = { @@ -27,6 +28,15 @@ export type GuardConfig = { store: LicenseStore; /** Horas que um binding valido anterior ainda e aceito se o license-server estiver inalcancavel. Default 72h. */ graceHours?: number; + /** + * "server" (default, compatibilidade com o uso atual): fingerprint pelo MAC da maquina — para apps + * com dominio publico real (ex.: ledcloud-core). "desktop": fingerprint por um id estavel do SO + * (MachineGuid/IOPlatformUUID/machine-id) em vez do MAC, que pode mudar entre boots num + * notebook/desktop (troca de adaptador, VPN, docking station) e gerar FINGERPRINT_MISMATCH falso. + * Nesse modo, `domain` normalmente e um identificador sintetico da instalacao (ex.: UUID gerado + * na ativacao), nao um dominio de verdade. + */ + platform?: "server" | "desktop"; }; export type GuardResult = @@ -39,7 +49,7 @@ export type GuardResult = */ export async function checkLicense(licenseKey: string | undefined, cfg: GuardConfig): Promise { const existing = await cfg.store.get(); - const fingerprint = getServerFingerprint(cfg.domain); + const fingerprint = cfg.platform === "desktop" ? getDesktopFingerprint(cfg.domain) : getServerFingerprint(cfg.domain); const key = licenseKey ?? existing?.licenseKey; if (!key) return { ok: false, reason: "NO_LICENSE", binding: existing }; diff --git a/src/index.ts b/src/index.ts index 1b7ff68..6f642fc 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1,6 @@ export { checkLicense } from "./guard"; export type { LicenseStore, LicenseBindingRecord, GuardConfig, GuardResult } from "./guard"; export { getServerFingerprint } from "./fingerprint"; +export { getMachineId, getDesktopFingerprint } from "./machine-id"; export { validateAgainstServer } from "./validate"; export type { ValidateResponse, ValidateOptions } from "./validate"; diff --git a/src/machine-id.ts b/src/machine-id.ts new file mode 100644 index 0000000..f5ebe18 --- /dev/null +++ b/src/machine-id.ts @@ -0,0 +1,74 @@ +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import { createHash } from "node:crypto"; + +/** + * Identificador estavel da MAQUINA (nao da interface de rede), para apps desktop/locais que nao tem + * dominio publico e onde o MAC pode mudar entre boots (troca de adaptador, VPN, docking station) — + * usar getServerFingerprint (MAC) nesses casos gera FINGERPRINT_MISMATCH falso em cliente legitimo. + * + * Cada SO expoe um id de instalacao que sobrevive a trocas de hardware de rede: + * - Windows: MachineGuid do registro (gerado na instalacao do Windows). + * - macOS: IOPlatformUUID (gerado na primeira inicializacao do hardware). + * - Linux: /etc/machine-id (systemd) ou /var/lib/dbus/machine-id. + * + * Nenhum desses e infalivel (reinstalar o SO troca o id; cloná-lo pra uma VM/imagem pode duplicá-lo), + * mas sao muito mais estaveis que o MAC pro mesmo uso continuo da MESMA instalacao. + */ +function readWindowsMachineGuid(): string | null { + try { + const out = execFileSync("reg", ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"], { encoding: "utf8", windowsHide: true }); + const m = out.match(/MachineGuid\s+REG_SZ\s+([0-9a-fA-F-]+)/); + return m?.[1] ?? null; + } catch { + return null; + } +} + +function readMacPlatformUuid(): string | null { + try { + const out = execFileSync("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], { encoding: "utf8" }); + const m = out.match(/"IOPlatformUUID"\s*=\s*"([0-9A-Fa-f-]+)"/); + return m?.[1] ?? null; + } catch { + return null; + } +} + +function readLinuxMachineId(): string | null { + for (const path of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) { + try { + const id = readFileSync(path, "utf8").trim(); + if (id) return id; + } catch { + // tenta o proximo caminho + } + } + return null; +} + +/** Melhor id estavel disponivel no SO atual, ou null se nenhum foi encontrado (chamador decide o fallback). */ +export function getMachineId(): string | null { + switch (process.platform) { + case "win32": + return readWindowsMachineGuid(); + case "darwin": + return readMacPlatformUuid(); + case "linux": + return readLinuxMachineId(); + default: + return null; + } +} + +/** + * Fingerprint para apps desktop/locais (sem dominio publico): usa o id estavel do SO + `domain` + * (aqui tipicamente um identificador sintetico da instalacao, ex.: um UUID gerado na ativacao e + * persistido localmente pelo app — NUNCA derivado de hardware). Se nenhum id de SO for encontrado, + * cai para um fallback fixo por processo (sem persistencia): o chamador deve tratar esse caso + * tratando `domain` como a unica fonte de estabilidade (ou gerando seu proprio id persistido). + */ +export function getDesktopFingerprint(domain: string): string { + const machineId = getMachineId() ?? "sem-machine-id"; + return createHash("sha256").update(`${machineId}|${domain.toLowerCase()}`).digest("hex"); +}