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>
This commit is contained in:
Leonardo Biasoli 2026-11-15 11:22:36 -03:00
parent 0afaf1c38e
commit 75d724291b
4 changed files with 120 additions and 1 deletions

View file

@ -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`) ## Motivos de falha (`result.reason`)
| Motivo | Significado | | Motivo | Significado |

View file

@ -1,4 +1,5 @@
import { getServerFingerprint } from "./fingerprint"; import { getServerFingerprint } from "./fingerprint";
import { getDesktopFingerprint } from "./machine-id";
import { validateAgainstServer } from "./validate"; import { validateAgainstServer } from "./validate";
export type LicenseBindingRecord = { export type LicenseBindingRecord = {
@ -27,6 +28,15 @@ export type GuardConfig = {
store: LicenseStore; store: LicenseStore;
/** Horas que um binding valido anterior ainda e aceito se o license-server estiver inalcancavel. Default 72h. */ /** Horas que um binding valido anterior ainda e aceito se o license-server estiver inalcancavel. Default 72h. */
graceHours?: number; 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 = export type GuardResult =
@ -39,7 +49,7 @@ export type GuardResult =
*/ */
export async function checkLicense(licenseKey: string | undefined, cfg: GuardConfig): Promise<GuardResult> { export async function checkLicense(licenseKey: string | undefined, cfg: GuardConfig): Promise<GuardResult> {
const existing = await cfg.store.get(); 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; const key = licenseKey ?? existing?.licenseKey;
if (!key) return { ok: false, reason: "NO_LICENSE", binding: existing }; if (!key) return { ok: false, reason: "NO_LICENSE", binding: existing };

View file

@ -1,5 +1,6 @@
export { checkLicense } from "./guard"; export { checkLicense } from "./guard";
export type { LicenseStore, LicenseBindingRecord, GuardConfig, GuardResult } from "./guard"; export type { LicenseStore, LicenseBindingRecord, GuardConfig, GuardResult } from "./guard";
export { getServerFingerprint } from "./fingerprint"; export { getServerFingerprint } from "./fingerprint";
export { getMachineId, getDesktopFingerprint } from "./machine-id";
export { validateAgainstServer } from "./validate"; export { validateAgainstServer } from "./validate";
export type { ValidateResponse, ValidateOptions } from "./validate"; export type { ValidateResponse, ValidateOptions } from "./validate";

74
src/machine-id.ts Normal file
View file

@ -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");
}