@carchalabs/licensekit-electron 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bugra Omer Aydemir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @carchalabs/licensekit-electron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [LicenseKit](https://licensekit.carchalabs.com) SDK. It runs in the Electron main process or in plain Node. It activates a license key on this device, saves the signed lease, and verifies it offline with your public keys.
+
+```js
+const { LicenseKit } = require('@carchalabs/licensekit-electron');
+
+const kit = new LicenseKit({
+  serverUrl: 'https://licenses.example.com',
+  product: 'example-studio',
+  publicKey: [currentKeyPem, nextKeyPem],
+  storageDir: app.getPath('userData'),
+  secureStore: {
+    encrypt: (s) => safeStorage.encryptString(s),
+    decrypt: (b) => safeStorage.decryptString(b),
+  },
+});
+
+const state = await kit.check();
+if (state.status === 'unlicensed') await kit.activate(userEnteredKey);
+if (LicenseKit.hasFeature(state, 'export-pdf')) exportPdf();
+```
+
+`check()` returns one of `valid`, `grace`, `invalid`, `unlicensed` or `clock_suspect`, with `offline` and `storageProtected` flags. `activate(key, machineName)` sends the device name you pass; the default is the computer's host name. `deactivate()` releases the seat.
+
+The SDK sends the license key, a per-product SHA-256 hash of the operating system's machine ID, the device name, the platform and your app version. The raw machine ID does not leave the computer.
+
+Full reference: [licensekit.carchalabs.com/docs](https://licensekit.carchalabs.com/docs/#sdk). Requires Node 22.13 or later. MIT License.

package/dist/fingerprint.d.ts

@@ -0,0 +1,2 @@
+/** Reads a stable, OS-provided machine id. Falls back to hardware traits if unavailable. */
+export declare function readMachineId(): Promise<string>;

package/dist/fingerprint.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMachineId = readMachineId;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_util_1 = require("node:util");
+const run = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/** Reads a stable, OS-provided machine id. Falls back to hardware traits if unavailable. */
+async function readMachineId() {
+    try {
+        const os = (0, node_os_1.platform)();
+        if (os === 'darwin') {
+            const { stdout } = await run('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { timeout: 3000 });
+            const m = stdout.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+            if (m)
+                return `mac:${m[1]}`;
+        }
+        else if (os === 'win32') {
+            const { stdout } = await run('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], {
+                timeout: 3000,
+                windowsHide: true,
+            });
+            const m = stdout.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
+            if (m)
+                return `win:${m[1]}`;
+        }
+        else {
+            for (const f of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+                const id = (await (0, promises_1.readFile)(f, 'utf8').catch(() => '')).trim();
+                if (id)
+                    return `linux:${id}`;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return `fallback:${fallbackTraits()}`;
+}
+function fallbackTraits() {
+    const macs = Object.values((0, node_os_1.networkInterfaces)())
+        .flat()
+        .filter((i) => i && !i.internal && i.mac && i.mac !== '00:00:00:00:00:00')
+        .map((i) => i.mac)
+        .sort();
+    return [(0, node_os_1.hostname)(), (0, node_os_1.cpus)()[0]?.model ?? '', macs[0] ?? ''].join('|');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":";;AAQA,sCAwBC;AAhCD,2DAA8C;AAC9C,+CAA4C;AAC5C,qCAAsE;AACtE,yCAAsC;AAEtC,MAAM,GAAG,GAAG,IAAA,qBAAS,EAAC,6BAAQ,CAAC,CAAC;AAEhC,4FAA4F;AACrF,KAAK,UAAU,aAAa;IACjC,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAA,kBAAQ,GAAE,CAAC;QACtB,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;YACpB,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,wBAAwB,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACnG,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;YAC3D,IAAI,CAAC;gBAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,CAAC;aAAM,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YAC1B,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,yCAAyC,EAAE,IAAI,EAAE,aAAa,CAAC,EAAE;gBAC7G,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;YAC3D,IAAI,CAAC;gBAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,0BAA0B,CAAC,EAAE,CAAC;gBAChE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAA,mBAAQ,EAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC9D,IAAI,EAAE;oBAAE,OAAO,SAAS,EAAE,EAAE,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,YAAY,cAAc,EAAE,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAA,2BAAiB,GAAE,CAAC;SAC5C,IAAI,EAAE;SACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,mBAAmB,CAAC;SACzE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAE,CAAC,GAAG,CAAC;SAClB,IAAI,EAAE,CAAC;IACV,OAAO,CAAC,IAAA,kBAAQ,GAAE,EAAE,IAAA,cAAI,GAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { readMachineId } from './fingerprint';
+export { readMachineId };
+export type LicenseStatus = 'valid' | 'grace' | 'invalid' | 'unlicensed' | 'clock_suspect';
+export interface LicenseState {
+    status: LicenseStatus;
+    offline: boolean;
+    storageProtected: boolean;
+    reason?: string;
+    message?: string;
+    customer?: string;
+    features: string[];
+    expiresAt: string | null;
+    maintenanceUntil?: string | null;
+    revalidateBy?: string;
+    keyHint?: string;
+}
+export interface SecureStore {
+    encrypt(plain: string): Buffer | Promise<Buffer>;
+    decrypt(cipher: Buffer): string | Promise<string>;
+    isProtected?(): boolean;
+}
+export interface LicenseKitOptions {
+    serverUrl: string;
+    product: string;
+    publicKey: string | string[];
+    storageDir: string;
+    appVersion?: string;
+    graceDays?: number;
+    secureStore?: SecureStore;
+    requestTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    machineId?: () => Promise<string>;
+    now?: () => number;
+}
+export declare class LicenseError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+export declare class LicenseKit {
+    private readonly opts;
+    private readonly file;
+    private readonly keys;
+    private fingerprintCache?;
+    constructor(opts: LicenseKitOptions);
+    private get fetch();
+    private nowSec;
+    private get storageProtected();
+    fingerprint(): Promise<string>;
+    private load;
+    private save;
+    private clear;
+    private post;
+    private emptyState;
+    private stateFromLease;
+    activate(licenseKey: string, machineName?: string): Promise<LicenseState>;
+    check(): Promise<LicenseState>;
+    deactivate(): Promise<void>;
+    static hasFeature(state: LicenseState, feature: string): boolean;
+}

package/dist/index.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LicenseKit = exports.LicenseError = exports.readMachineId = void 0;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const licensekit_core_1 = require("@carchalabs/licensekit-core");
+const fingerprint_1 = require("./fingerprint");
+Object.defineProperty(exports, "readMachineId", { enumerable: true, get: function () { return fingerprint_1.readMachineId; } });
+const DEFINITIVE = new Set(['invalid_key', 'not_activated', 'license_suspended', 'license_revoked', 'license_expired']);
+const CLOCK_TOLERANCE_SECONDS = 24 * 3600;
+const DEFAULT_GRACE_DAYS = 7;
+const CLOCK_MESSAGE = 'The date and time on this computer look wrong. Correct them, then connect to the internet.';
+class LicenseError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'LicenseError';
+    }
+}
+exports.LicenseError = LicenseError;
+const REASON_TEXT = {
+    malformed: 'The saved license is damaged. Please activate again.',
+    bad_signature: 'The saved license was modified. Please activate again.',
+    unsupported_algorithm: 'Please update the app.',
+    wrong_type: 'Please update the app.',
+    unknown_key: 'Please update the app.',
+    wrong_issuer: 'This license was issued by a different license server.',
+    not_yet_valid: CLOCK_MESSAGE,
+    wrong_product: 'This license is for a different product.',
+    wrong_device: 'This license is activated on another device.',
+    expired: 'Your license has expired.',
+    revalidation_required: 'Connect to the internet to confirm your license.',
+};
+const toIso = (seconds) => new Date(seconds * 1000).toISOString();
+class LicenseKit {
+    opts;
+    file;
+    keys;
+    fingerprintCache;
+    constructor(opts) {
+        this.opts = opts;
+        this.file = (0, node_path_1.join)(opts.storageDir, 'license.dat');
+        this.keys = (0, licensekit_core_1.keySet)(Array.isArray(opts.publicKey) ? opts.publicKey : [opts.publicKey]);
+    }
+    get fetch() {
+        return this.opts.fetchImpl ?? fetch;
+    }
+    nowSec() {
+        return Math.floor((this.opts.now?.() ?? Date.now()) / 1000);
+    }
+    get storageProtected() {
+        const store = this.opts.secureStore;
+        return store !== undefined && (store.isProtected?.() ?? true);
+    }
+    async fingerprint() {
+        if (!this.fingerprintCache) {
+            const raw = await (this.opts.machineId ?? fingerprint_1.readMachineId)();
+            this.fingerprintCache = (0, licensekit_core_1.hashFingerprint)(raw, this.opts.product);
+        }
+        return this.fingerprintCache;
+    }
+    async load() {
+        try {
+            const buf = await (0, promises_1.readFile)(this.file);
+            const text = this.opts.secureStore ? await this.opts.secureStore.decrypt(buf) : buf.toString('utf8');
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(stored) {
+        await (0, promises_1.mkdir)(this.opts.storageDir, { recursive: true });
+        const text = JSON.stringify(stored);
+        await (0, promises_1.writeFile)(this.file, this.opts.secureStore ? await this.opts.secureStore.encrypt(text) : text, { mode: 0o600 });
+    }
+    async clear() {
+        await (0, promises_1.rm)(this.file, { force: true });
+    }
+    async post(path, body) {
+        let res;
+        try {
+            res = await this.fetch(this.opts.serverUrl.replace(/\/+$/, '') + path, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.opts.requestTimeoutMs ?? 8000),
+            });
+        }
+        catch {
+            throw new LicenseError('network', 'Could not reach the license server.');
+        }
+        const json = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new LicenseError(json.error ?? 'server_error', json.message ?? `License server error (${res.status})`, res.status);
+        return json;
+    }
+    emptyState(status, offline, extra = {}) {
+        return { status, offline, storageProtected: this.storageProtected, features: [], expiresAt: null, ...extra };
+    }
+    stateFromLease(stored, offline) {
+        const fingerprintHash = this.fingerprintCache;
+        const now = this.nowSec();
+        const keyHint = `${stored.licenseKey.slice(0, 7)}…${stored.licenseKey.slice(-4)}`;
+        if (offline && stored.lastSeen !== undefined && now < stored.lastSeen - CLOCK_TOLERANCE_SECONDS) {
+            return this.emptyState('clock_suspect', offline, { reason: 'clock_rollback', message: CLOCK_MESSAGE, keyHint });
+        }
+        const verifyOptions = { keys: this.keys, product: this.opts.product, fingerprintHash, now };
+        const strict = (0, licensekit_core_1.verifyLease)(stored.token, verifyOptions);
+        const fromClaims = (claims) => ({
+            customer: claims.cus,
+            features: claims.feat,
+            expiresAt: claims.exp === undefined ? null : toIso(claims.exp),
+            maintenanceUntil: claims.mnt === undefined ? null : toIso(claims.mnt),
+            storageProtected: this.storageProtected,
+            keyHint,
+        });
+        if (strict.ok) {
+            return { status: 'valid', offline, ...fromClaims(strict.claims), revalidateBy: toIso(strict.claims.rev) };
+        }
+        if (strict.reason === 'not_yet_valid') {
+            return this.emptyState('clock_suspect', offline, { reason: 'lease_from_future', message: CLOCK_MESSAGE, keyHint });
+        }
+        if (strict.reason === 'revalidation_required' && strict.claims) {
+            const grace = strict.claims.grc ?? (this.opts.graceDays ?? DEFAULT_GRACE_DAYS) * 86400;
+            const lenient = (0, licensekit_core_1.verifyLease)(stored.token, { ...verifyOptions, graceSeconds: grace });
+            if (lenient.ok) {
+                return {
+                    status: 'grace',
+                    offline,
+                    reason: 'offline_grace',
+                    message: 'Working offline. Connect to the internet soon to keep using the app.',
+                    ...fromClaims(lenient.claims),
+                    revalidateBy: toIso(Math.min(lenient.claims.rev + grace, lenient.claims.exp ?? Infinity)),
+                };
+            }
+        }
+        return this.emptyState('invalid', offline, { reason: strict.reason, message: REASON_TEXT[strict.reason], keyHint });
+    }
+    async activate(licenseKey, machineName = (0, node_os_1.hostname)()) {
+        const fingerprint = await this.fingerprint();
+        const key = licenseKey.trim().toUpperCase();
+        const response = await this.post('/v1/activate', {
+            licenseKey: key,
+            product: this.opts.product,
+            fingerprint,
+            machineName: machineName.slice(0, 80),
+            platform: (0, node_os_1.platform)(),
+            appVersion: this.opts.appVersion,
+        });
+        const stored = { licenseKey: key, token: response.token, lastSeen: this.nowSec() };
+        const state = this.stateFromLease(stored, false);
+        if (state.status !== 'valid')
+            throw new LicenseError(state.status === 'clock_suspect' ? 'clock_suspect' : state.reason ?? 'invalid', state.message ?? 'Server returned an unusable license');
+        await this.save(stored);
+        return state;
+    }
+    async check() {
+        await this.fingerprint();
+        const stored = await this.load();
+        if (!stored)
+            return this.emptyState('unlicensed', false);
+        try {
+            const response = await this.post('/v1/validate', {
+                licenseKey: stored.licenseKey,
+                product: this.opts.product,
+                fingerprint: this.fingerprintCache,
+                appVersion: this.opts.appVersion,
+            });
+            const fresh = { ...stored, token: response.token, lastSeen: this.nowSec() };
+            await this.save(fresh);
+            return this.stateFromLease(fresh, false);
+        }
+        catch (e) {
+            if (e instanceof LicenseError && DEFINITIVE.has(e.code)) {
+                return this.emptyState('invalid', false, { reason: e.code, message: e.message });
+            }
+            const state = this.stateFromLease(stored, true);
+            if (state.status === 'valid' || state.status === 'grace') {
+                await this.save({ ...stored, lastSeen: Math.max(stored.lastSeen ?? 0, this.nowSec()) });
+            }
+            return state;
+        }
+    }
+    async deactivate() {
+        const stored = await this.load();
+        if (!stored)
+            return;
+        try {
+            await this.post('/v1/deactivate', { licenseKey: stored.licenseKey, product: this.opts.product, fingerprint: await this.fingerprint() });
+        }
+        catch (e) {
+            if (!(e instanceof LicenseError && (e.code === 'not_activated' || e.code === 'invalid_key')))
+                throw e;
+        }
+        await this.clear();
+    }
+    static hasFeature(state, feature) {
+        return (state.status === 'valid' || state.status === 'grace') && state.features.includes(feature);
+    }
+}
+exports.LicenseKit = LicenseKit;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,+CAAkE;AAClE,qCAA6C;AAC7C,yCAAiC;AACjC,iEAA8G;AAC9G,+CAA8C;AAErC,8FAFA,2BAAa,OAEA;AA4CtB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,CAAC,CAAC;AACxH,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,CAAC;AAC1C,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAC7B,MAAM,aAAa,GAAG,4FAA4F,CAAC;AAEnH,MAAa,YAAa,SAAQ,KAAK;IAEnB;IAEA;IAHlB,YACkB,IAAY,EAC5B,OAAe,EACC,MAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAAS;QAG/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AATD,oCASC;AAED,MAAM,WAAW,GAAiC;IAChD,SAAS,EAAE,sDAAsD;IACjE,aAAa,EAAE,wDAAwD;IACvE,qBAAqB,EAAE,wBAAwB;IAC/C,UAAU,EAAE,wBAAwB;IACpC,WAAW,EAAE,wBAAwB;IACrC,YAAY,EAAE,wDAAwD;IACtE,aAAa,EAAE,aAAa;IAC5B,aAAa,EAAE,0CAA0C;IACzD,YAAY,EAAE,8CAA8C;IAC5D,OAAO,EAAE,2BAA2B;IACpC,qBAAqB,EAAE,kDAAkD;CAC1E,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AAE1E,MAAa,UAAU;IAKQ;IAJZ,IAAI,CAAS;IACb,IAAI,CAAyB;IACtC,gBAAgB,CAAU;IAElC,YAA6B,IAAuB;QAAvB,SAAI,GAAJ,IAAI,CAAmB;QAClD,IAAI,CAAC,IAAI,GAAG,IAAA,gBAAI,EAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,IAAA,wBAAM,EAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,IAAY,KAAK;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IACtC,CAAC;IAEO,MAAM;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,IAAY,gBAAgB;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;QACpC,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,2BAAa,CAAC,EAAE,CAAC;YAC3D,IAAI,CAAC,gBAAgB,GAAG,IAAA,iCAAe,EAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACrG,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,MAAc;QAC/B,MAAM,IAAA,gBAAK,EAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,IAAA,oBAAS,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxH,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,MAAM,IAAA,aAAE,EAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAA6B;QAC5D,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE;gBACrE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC;aAChE,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,qCAAqC,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,IAAI,GAAQ,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,cAAc,EAAE,IAAI,CAAC,OAAO,IAAI,yBAAyB,GAAG,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACtI,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,UAAU,CAAC,MAAqB,EAAE,OAAgB,EAAE,QAA+B,EAAE;QAC3F,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;IAC/G,CAAC;IAEO,cAAc,CAAC,MAAc,EAAE,OAAgB;QACrD,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAiB,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,GAAG,GAAG,MAAM,CAAC,QAAQ,GAAG,uBAAuB,EAAE,CAAC;YAChG,OAAO,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;QAClH,CAAC;QACD,MAAM,aAAa,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC;QAC5F,MAAM,MAAM,GAAG,IAAA,6BAAW,EAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,CAAC,MAAmB,EAAE,EAAE,CAAC,CAAC;YAC3C,QAAQ,EAAE,MAAM,CAAC,GAAG;YACpB,QAAQ,EAAE,MAAM,CAAC,IAAI;YACrB,SAAS,EAAE,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;YAC9D,gBAAgB,EAAE,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;YACrE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,OAAO;SACR,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5G,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,eAAe,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;QACrH,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC,GAAG,KAAK,CAAC;YACvF,MAAM,OAAO,GAAG,IAAA,6BAAW,EAAC,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,aAAa,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;YACrF,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO;oBACL,MAAM,EAAE,OAAO;oBACf,OAAO;oBACP,MAAM,EAAE,eAAe;oBACvB,OAAO,EAAE,sEAAsE;oBAC/E,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;oBAC7B,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC;iBAC1F,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACtH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,UAAkB,EAAE,WAAW,GAAG,IAAA,kBAAQ,GAAE;QACzD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;YAC/C,UAAU,EAAE,GAAG;YACf,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;YAC1B,WAAW;YACX,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACrC,QAAQ,EAAE,IAAA,kBAAQ,GAAE;YACpB,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU;SACjC,CAAC,CAAC;QACH,MAAM,MAAM,GAAW,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3F,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO;YAAE,MAAM,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,KAAK,CAAC,OAAO,IAAI,qCAAqC,CAAC,CAAC;QAC7L,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACzD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;gBAC/C,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;gBAC1B,WAAW,EAAE,IAAI,CAAC,gBAAgB;gBAClC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU;aACjC,CAAC,CAAC;YACH,MAAM,KAAK,GAAW,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACpF,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxD,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACnF,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAChD,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;gBACzD,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;YAC1F,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAC1I,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,CAAC,CAAC,YAAY,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC;gBAAE,MAAM,CAAC,CAAC;QACxG,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,KAAmB,EAAE,OAAe;QACpD,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpG,CAAC;CACF;AA1KD,gCA0KC"}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@carchalabs/licensekit-electron",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "LicenseKit SDK for the Electron main process and Node: activation, offline verification, grace period",
+  "homepage": "https://licensekit.carchalabs.com/docs/",
+  "repository": { "type": "git", "url": "git+https://github.com/carcha-labs/licensekit-sdk.git", "directory": "packages/sdk-electron" },
+  "bugs": { "url": "https://github.com/carcha-labs/licensekit-sdk/issues" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src", "!dist/**/*.test.*", "!src/**/*.test.ts"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "node --no-warnings=ExperimentalWarning --test dist/*.test.js"
+  },
+  "dependencies": {
+    "@carchalabs/licensekit-core": "0.1.0"
+  },
+  "engines": { "node": ">=22.13" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT"
+}

package/src/fingerprint.ts

@@ -0,0 +1,42 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { cpus, hostname, networkInterfaces, platform } from 'node:os';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/** Reads a stable, OS-provided machine id. Falls back to hardware traits if unavailable. */
+export async function readMachineId(): Promise<string> {
+  try {
+    const os = platform();
+    if (os === 'darwin') {
+      const { stdout } = await run('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { timeout: 3000 });
+      const m = stdout.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+      if (m) return `mac:${m[1]}`;
+    } else if (os === 'win32') {
+      const { stdout } = await run('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], {
+        timeout: 3000,
+        windowsHide: true,
+      });
+      const m = stdout.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
+      if (m) return `win:${m[1]}`;
+    } else {
+      for (const f of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+        const id = (await readFile(f, 'utf8').catch(() => '')).trim();
+        if (id) return `linux:${id}`;
+      }
+    }
+  } catch {
+    /* fall through */
+  }
+  return `fallback:${fallbackTraits()}`;
+}
+
+function fallbackTraits(): string {
+  const macs = Object.values(networkInterfaces())
+    .flat()
+    .filter((i) => i && !i.internal && i.mac && i.mac !== '00:00:00:00:00:00')
+    .map((i) => i!.mac)
+    .sort();
+  return [hostname(), cpus()[0]?.model ?? '', macs[0] ?? ''].join('|');
+}

package/src/index.ts

@@ -0,0 +1,254 @@
+import { KeyObject } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { hostname, platform } from 'node:os';
+import { join } from 'node:path';
+import { hashFingerprint, keySet, LeaseClaims, LeaseFailure, verifyLease } from '@carchalabs/licensekit-core';
+import { readMachineId } from './fingerprint';
+
+export { readMachineId };
+
+export type LicenseStatus = 'valid' | 'grace' | 'invalid' | 'unlicensed' | 'clock_suspect';
+
+export interface LicenseState {
+  status: LicenseStatus;
+  offline: boolean;
+  storageProtected: boolean;
+  reason?: string;
+  message?: string;
+  customer?: string;
+  features: string[];
+  expiresAt: string | null;
+  maintenanceUntil?: string | null;
+  revalidateBy?: string;
+  keyHint?: string;
+}
+
+export interface SecureStore {
+  encrypt(plain: string): Buffer | Promise<Buffer>;
+  decrypt(cipher: Buffer): string | Promise<string>;
+  isProtected?(): boolean;
+}
+
+export interface LicenseKitOptions {
+  serverUrl: string;
+  product: string;
+  publicKey: string | string[];
+  storageDir: string;
+  appVersion?: string;
+  graceDays?: number;
+  secureStore?: SecureStore;
+  requestTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  machineId?: () => Promise<string>;
+  now?: () => number;
+}
+
+interface Stored {
+  licenseKey: string;
+  token: string;
+  lastSeen?: number;
+}
+
+const DEFINITIVE = new Set(['invalid_key', 'not_activated', 'license_suspended', 'license_revoked', 'license_expired']);
+const CLOCK_TOLERANCE_SECONDS = 24 * 3600;
+const DEFAULT_GRACE_DAYS = 7;
+const CLOCK_MESSAGE = 'The date and time on this computer look wrong. Correct them, then connect to the internet.';
+
+export class LicenseError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly status?: number,
+  ) {
+    super(message);
+    this.name = 'LicenseError';
+  }
+}
+
+const REASON_TEXT: Record<LeaseFailure, string> = {
+  malformed: 'The saved license is damaged. Please activate again.',
+  bad_signature: 'The saved license was modified. Please activate again.',
+  unsupported_algorithm: 'Please update the app.',
+  wrong_type: 'Please update the app.',
+  unknown_key: 'Please update the app.',
+  wrong_issuer: 'This license was issued by a different license server.',
+  not_yet_valid: CLOCK_MESSAGE,
+  wrong_product: 'This license is for a different product.',
+  wrong_device: 'This license is activated on another device.',
+  expired: 'Your license has expired.',
+  revalidation_required: 'Connect to the internet to confirm your license.',
+};
+
+const toIso = (seconds: number) => new Date(seconds * 1000).toISOString();
+
+export class LicenseKit {
+  private readonly file: string;
+  private readonly keys: Map<string, KeyObject>;
+  private fingerprintCache?: string;
+
+  constructor(private readonly opts: LicenseKitOptions) {
+    this.file = join(opts.storageDir, 'license.dat');
+    this.keys = keySet(Array.isArray(opts.publicKey) ? opts.publicKey : [opts.publicKey]);
+  }
+
+  private get fetch() {
+    return this.opts.fetchImpl ?? fetch;
+  }
+
+  private nowSec() {
+    return Math.floor((this.opts.now?.() ?? Date.now()) / 1000);
+  }
+
+  private get storageProtected(): boolean {
+    const store = this.opts.secureStore;
+    return store !== undefined && (store.isProtected?.() ?? true);
+  }
+
+  async fingerprint(): Promise<string> {
+    if (!this.fingerprintCache) {
+      const raw = await (this.opts.machineId ?? readMachineId)();
+      this.fingerprintCache = hashFingerprint(raw, this.opts.product);
+    }
+    return this.fingerprintCache;
+  }
+
+  private async load(): Promise<Stored | null> {
+    try {
+      const buf = await readFile(this.file);
+      const text = this.opts.secureStore ? await this.opts.secureStore.decrypt(buf) : buf.toString('utf8');
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  }
+
+  private async save(stored: Stored) {
+    await mkdir(this.opts.storageDir, { recursive: true });
+    const text = JSON.stringify(stored);
+    await writeFile(this.file, this.opts.secureStore ? await this.opts.secureStore.encrypt(text) : text, { mode: 0o600 });
+  }
+
+  private async clear() {
+    await rm(this.file, { force: true });
+  }
+
+  private async post(path: string, body: Record<string, unknown>): Promise<any> {
+    let res: Response;
+    try {
+      res = await this.fetch(this.opts.serverUrl.replace(/\/+$/, '') + path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.opts.requestTimeoutMs ?? 8000),
+      });
+    } catch {
+      throw new LicenseError('network', 'Could not reach the license server.');
+    }
+    const json: any = await res.json().catch(() => ({}));
+    if (!res.ok) throw new LicenseError(json.error ?? 'server_error', json.message ?? `License server error (${res.status})`, res.status);
+    return json;
+  }
+
+  private emptyState(status: LicenseStatus, offline: boolean, extra: Partial<LicenseState> = {}): LicenseState {
+    return { status, offline, storageProtected: this.storageProtected, features: [], expiresAt: null, ...extra };
+  }
+
+  private stateFromLease(stored: Stored, offline: boolean): LicenseState {
+    const fingerprintHash = this.fingerprintCache!;
+    const now = this.nowSec();
+    const keyHint = `${stored.licenseKey.slice(0, 7)}…${stored.licenseKey.slice(-4)}`;
+    if (offline && stored.lastSeen !== undefined && now < stored.lastSeen - CLOCK_TOLERANCE_SECONDS) {
+      return this.emptyState('clock_suspect', offline, { reason: 'clock_rollback', message: CLOCK_MESSAGE, keyHint });
+    }
+    const verifyOptions = { keys: this.keys, product: this.opts.product, fingerprintHash, now };
+    const strict = verifyLease(stored.token, verifyOptions);
+    const fromClaims = (claims: LeaseClaims) => ({
+      customer: claims.cus,
+      features: claims.feat,
+      expiresAt: claims.exp === undefined ? null : toIso(claims.exp),
+      maintenanceUntil: claims.mnt === undefined ? null : toIso(claims.mnt),
+      storageProtected: this.storageProtected,
+      keyHint,
+    });
+    if (strict.ok) {
+      return { status: 'valid', offline, ...fromClaims(strict.claims), revalidateBy: toIso(strict.claims.rev) };
+    }
+    if (strict.reason === 'not_yet_valid') {
+      return this.emptyState('clock_suspect', offline, { reason: 'lease_from_future', message: CLOCK_MESSAGE, keyHint });
+    }
+    if (strict.reason === 'revalidation_required' && strict.claims) {
+      const grace = strict.claims.grc ?? (this.opts.graceDays ?? DEFAULT_GRACE_DAYS) * 86400;
+      const lenient = verifyLease(stored.token, { ...verifyOptions, graceSeconds: grace });
+      if (lenient.ok) {
+        return {
+          status: 'grace',
+          offline,
+          reason: 'offline_grace',
+          message: 'Working offline. Connect to the internet soon to keep using the app.',
+          ...fromClaims(lenient.claims),
+          revalidateBy: toIso(Math.min(lenient.claims.rev + grace, lenient.claims.exp ?? Infinity)),
+        };
+      }
+    }
+    return this.emptyState('invalid', offline, { reason: strict.reason, message: REASON_TEXT[strict.reason], keyHint });
+  }
+
+  async activate(licenseKey: string, machineName = hostname()): Promise<LicenseState> {
+    const fingerprint = await this.fingerprint();
+    const key = licenseKey.trim().toUpperCase();
+    const response = await this.post('/v1/activate', {
+      licenseKey: key,
+      product: this.opts.product,
+      fingerprint,
+      machineName: machineName.slice(0, 80),
+      platform: platform(),
+      appVersion: this.opts.appVersion,
+    });
+    const stored: Stored = { licenseKey: key, token: response.token, lastSeen: this.nowSec() };
+    const state = this.stateFromLease(stored, false);
+    if (state.status !== 'valid') throw new LicenseError(state.status === 'clock_suspect' ? 'clock_suspect' : state.reason ?? 'invalid', state.message ?? 'Server returned an unusable license');
+    await this.save(stored);
+    return state;
+  }
+
+  async check(): Promise<LicenseState> {
+    await this.fingerprint();
+    const stored = await this.load();
+    if (!stored) return this.emptyState('unlicensed', false);
+    try {
+      const response = await this.post('/v1/validate', {
+        licenseKey: stored.licenseKey,
+        product: this.opts.product,
+        fingerprint: this.fingerprintCache,
+        appVersion: this.opts.appVersion,
+      });
+      const fresh: Stored = { ...stored, token: response.token, lastSeen: this.nowSec() };
+      await this.save(fresh);
+      return this.stateFromLease(fresh, false);
+    } catch (e) {
+      if (e instanceof LicenseError && DEFINITIVE.has(e.code)) {
+        return this.emptyState('invalid', false, { reason: e.code, message: e.message });
+      }
+      const state = this.stateFromLease(stored, true);
+      if (state.status === 'valid' || state.status === 'grace') {
+        await this.save({ ...stored, lastSeen: Math.max(stored.lastSeen ?? 0, this.nowSec()) });
+      }
+      return state;
+    }
+  }
+
+  async deactivate(): Promise<void> {
+    const stored = await this.load();
+    if (!stored) return;
+    try {
+      await this.post('/v1/deactivate', { licenseKey: stored.licenseKey, product: this.opts.product, fingerprint: await this.fingerprint() });
+    } catch (e) {
+      if (!(e instanceof LicenseError && (e.code === 'not_activated' || e.code === 'invalid_key'))) throw e;
+    }
+    await this.clear();
+  }
+
+  static hasFeature(state: LicenseState, feature: string): boolean {
+    return (state.status === 'valid' || state.status === 'grace') && state.features.includes(feature);
+  }
+}