@carchalabs/seal-electron 0.6.2 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @carchalabs/seal-electron
 
-The [Carcha Seal](https://seal.carchalabs.com) (formerly LicenseKit) 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.
+The [Carcha Seal](https://seal.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 { Seal } = require('@carchalabs/seal-electron');
@@ -25,9 +25,21 @@ if (Seal.hasFeature(state, 'export-pdf')) exportPdf();
 
 Code can be protected the same way (Envelope): encrypt a CommonJS module or a folder of them with `seal-encrypt --feature pro dist/premium dist/premium`, and load it with `await kit.requireEncrypted('pro', path.join(__dirname, 'premium/index.js.lke'))`. Without the feature in the license the code cannot be read; a licensed user can still read it from memory.
 
+**Floating licenses.** For a license whose policy is floating (a pool of seats in use at the same time), take a seat when the app starts and give it back when it ends:
+
+```js
+const seat = await kit.checkout(userEnteredKey);      // later: kit.checkout() uses the saved key
+seat.on('lost', ({ reason, message }) => showLicenseScreen(message));
+if (seat.has('export-pdf')) exportPdf();
+// … and on your own sign-out or shutdown path:
+await seat.release();
+```
+
+The seat renews itself before its token's renewal time and emits `renewed`. When renewals get no answer it keeps trying until the token's lifetime has passed on a monotonic clock (changing the computer's clock changes nothing), then emits `lost` with `expired`; a refusal (`license_revoked`, `seats_exhausted`, …) emits `lost` with the server's reason at once. The SDK does nothing else on `lost`: your app decides. If the server ended the session or another copy renewed it, the SDK checks out again on the same seat. `checkout()` throws `seats_exhausted` with `details.inUse`, `details.total` and `details.retryAfter` (seconds) when every seat is in use, and `not_floating` for a node-locked license. Pass `{ user }` for a license that counts users (only a hash is sent) and `{ machineName }` to name the computer. In Electron the SDK releases held seats when the app quits (at most 2 seconds; `releaseOnQuit: false` turns it off); a seat that is never released frees itself when its token expires (10 minutes by default). Seat tokens live in memory only. With `@carchalabs/seal-hwid` 0.6 the seat is bound to the device key and every heartbeat carries a proof made in the native module.
+
 Computers that never reach the server use offline activation: `offlineRequest(key)` returns a request file, the license server turns it into a license file (its `/offline` page, `POST /v1/offline/activate` or the console), and `activateOffline(file)` loads it; it works only on that computer, for the policy's offline days. `deactivateOffline()` removes the license and returns a deactivation file the vendor uploads to free the seat. See the [documentation](https://seal.carchalabs.com/docs/#concepts).
 
-The SDK sends the license key, a per-product SHA-256 hash of the operating system's machine ID, the device name, the platform, your app version and its own version. The raw machine ID does not leave the computer.
+The SDK sends the license key, a per-product SHA-256 hash of the operating system's machine ID, the device name you pass, the platform, your app version and its own version; a seat checkout also sends a random per-run instance id hash. The raw machine ID does not leave the computer. Everything sent and kept is listed in [PRIVACY.md](../../PRIVACY.md).
 
 **Feature data.** `await kit.decrypt('pro', data)` returns data you encrypted for a feature (`encryptForFeature` in `@carchalabs/seal-core`, with the feature's content key from the console). It works offline from the stored lease and only on a device whose license includes the feature; without a license the data stays encrypted, so removing a license check from your app does not unlock it. With `@carchalabs/seal-hwid` 0.2 the native module does the decryption and the key never reaches JavaScript.
 

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { MachineIdUnavailableError, readMachineId } from './fingerprint';
+import { Seat } from './seat';
 export { MachineIdUnavailableError, readMachineId };
+export { Seat };
+export type { SeatLoss, SeatStatus } from './seat';
 /** This SDK's version, sent to the server so vendors can see (and require) which SDK each device runs. */
 export declare const SDK_VERSION: string;
 export type LicenseStatus = 'valid' | 'grace' | 'invalid' | 'unlicensed' | 'clock_suspect';
@@ -65,11 +68,34 @@ export interface SealOptions {
      */
     hardware?: false | (() => HardwareReport | null | Promise<HardwareReport | null>);
     now?: () => number;
+    /** Milliseconds on a monotonic clock, for how long a seat lasts (default performance.now). For tests. */
+    monotonic?: () => number;
+    /**
+     * Floating licenses, in Electron: when the app quits, give every seat it holds back first (at most 2 seconds), then
+     * exit. Default true. Without it, or in plain Node, a seat the app does not release frees itself when its token
+     * expires.
+     */
+    releaseOnQuit?: boolean;
+}
+/** seal.checkout()'s options. */
+export interface CheckoutOptions {
+    /** The user's name, for a license that counts by user. Only its hash is sent (SHA-256 with the product). */
+    user?: string;
+    /** The name to show the vendor for this computer, as for activate. */
+    machineName?: string;
+    /** Renew before the token's renewal time without being asked (default true). false: call seat.renew() yourself. */
+    renewAutomatically?: boolean;
 }
+/** @internal for tests: the native module to use instead of the installed one (null: none). */
+export declare function useHwidModule(module: unknown): void;
 export declare class LicenseError extends Error {
     readonly code: string;
     readonly status?: number | undefined;
-    constructor(code: string, message: string, status?: number | undefined);
+    /** The refusal's other fields: for seats_exhausted, inUse, total and retryAfter (seconds); for rate_limited, retryAfter. */
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, status?: number | undefined, 
+    /** The refusal's other fields: for seats_exhausted, inUse, total and retryAfter (seconds); for rate_limited, retryAfter. */
+    details?: Record<string, unknown> | undefined);
 }
 export declare class Seal {
     private readonly opts;
@@ -106,10 +132,16 @@ export declare class Seal {
     private emptyState;
     /**
      * The device's public key, sent with activation and check-ins so the server wraps feature keys for
-     * this machine only. Only when the native module verifies for this app (it then also decrypts, with
-     * the matching secret it derives itself) and hardware is not turned off. Never throws.
+     * this machine only. Sent when the native module can also decrypt what is wrapped for it, with the
+     * matching secret it derives itself: through the compiled-in keys when they verify for this app, or,
+     * with seal-hwid 0.5+, through this app's own keys (every hosted vendor, a self-hosted server). Not
+     * with hardware turned off. Never throws.
      */
     private deviceKey;
+    /** The native module's decryption with this app's own keys (seal-hwid 0.5+), or null: older module, none, or hardware off. */
+    private deviceDecrypter;
+    /** This app's public keys as SPKI PEM, for the native module. */
+    private keyPems;
     /**
      * The native verifier, used only when its compiled-in keys include every key this app was given:
      * an app that trusts other keys (a self-hosted server) is checked by the JavaScript verifier alone.
@@ -133,8 +165,9 @@ export declare class Seal {
      * Decrypts data you encrypted for a feature (encryptForFeature in @carchalabs/seal-core, with the
      * feature's content key from the console). Works offline: it uses the saved lease, which must be valid
      * (or in its offline grace period), grant the feature and carry its key, and the saved license key.
-     * The native module does the work when it trusts this app's keys, so the content key never reaches
-     * JavaScript; without it the JavaScript implementation is used. Throws a LicenseError:
+     * When the lease is wrapped for this machine's device key, the native module does the work (with its
+     * compiled-in keys or, seal-hwid 0.5+, this app's keys), so the device secret and the content key never
+     * reach JavaScript; a lease wrapped for the license key alone is opened in JavaScript. Throws a LicenseError:
      * `unlicensed`, a lease failure reason, `clock_suspect`, `feature_not_licensed` or `decrypt_failed`.
      */
     decrypt(feature: string, data: Uint8Array): Promise<Buffer>;
@@ -179,8 +212,44 @@ export declare class Seal {
     private deactivateOfflineNow;
     deactivate(): Promise<void>;
     private deactivateNow;
+    /**
+     * Floating licenses: takes a seat of the license's pool for as long as the app runs (server docs/floating.md). With a
+     * license key, uses it and saves it for the next checkout; without, uses the saved one. The Seat renews itself, emits
+     * 'renewed' and, when the seat cannot be kept, 'lost' with the reason; give it back with seat.release() (in
+     * Electron the SDK also does on quit, see releaseOnQuit). There is no offline grace: a seat needs the server. Throws a
+     * LicenseError: `unlicensed`, the server's refusal (seats_exhausted with details inUse, total and retryAfter,
+     * not_floating for a node-locked license, license_revoked, …), `network`, or a seat token failure reason.
+     */
+    checkout(licenseKey?: string, options?: CheckoutOptions): Promise<Seat>;
+    private checkoutNow;
+    private seatHost;
+    /** The native module's seat proof (seal-hwid 0.6+), or null: older module, none, or hardware off. */
+    private seatProver;
+    /**
+     * The device key a seat is bound to, only when the native module can prove it in every heartbeat: a seat bound to a
+     * key the app cannot prove could not be renewed. Never throws.
+     */
+    private seatDeviceKey;
     static hasFeature(state: LicenseState, feature: string): boolean;
 }
+/** The part of Electron's app this uses. */
+export interface QuitApp {
+    on(event: 'will-quit', listener: (event: {
+        preventDefault(): void;
+        defaultPrevented?: boolean;
+    }) => void): unknown;
+    exit(code?: number): void;
+}
+/**
+ * In Electron, gives held seats back when the app quits: on will-quit (all windows closed, so no window can still cancel
+ * the quit) the quit is held, the seats are released (at most 2 seconds), and the app exits with app.exit(0), which does
+ * not emit before-quit or will-quit again (Electron's app API). Not when another listener already prevented the quit, nor
+ * when no seat is held. On Windows, Electron emits no quit event at shutdown or logout; seats then free themselves when
+ * their tokens expire. @internal exported for tests; `app` is Electron's when not given.
+ */
+export declare function installQuitRelease(app?: QuitApp): boolean;
+/** @internal for tests: forget the hook and the held seats. */
+export declare function resetQuitRelease(): void;
 /** The SDK class under its earlier name (LicenseKit). Same class; use Seal in new code. */
 export { Seal as LicenseKit };
 /** @deprecated The options under the class's earlier name; use SealOptions. */

package/dist/index.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LicenseKit = exports.Seal = exports.LicenseError = exports.SDK_VERSION = exports.readMachineId = exports.MachineIdUnavailableError = void 0;
+exports.LicenseKit = exports.Seal = exports.LicenseError = exports.SDK_VERSION = exports.Seat = exports.readMachineId = exports.MachineIdUnavailableError = void 0;
+exports.useHwidModule = useHwidModule;
+exports.installQuitRelease = installQuitRelease;
+exports.resetQuitRelease = resetQuitRelease;
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_module_1 = require("node:module");
@@ -11,6 +15,8 @@ const seal_core_1 = require("@carchalabs/seal-core");
 const fingerprint_1 = require("./fingerprint");
 Object.defineProperty(exports, "MachineIdUnavailableError", { enumerable: true, get: function () { return fingerprint_1.MachineIdUnavailableError; } });
 Object.defineProperty(exports, "readMachineId", { enumerable: true, get: function () { return fingerprint_1.readMachineId; } });
+const seat_1 = require("./seat");
+Object.defineProperty(exports, "Seat", { enumerable: true, get: function () { return seat_1.Seat; } });
 /** This SDK's version, sent to the server so vendors can see (and require) which SDK each device runs. */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 exports.SDK_VERSION = require('../package.json').version;
@@ -18,7 +24,9 @@ exports.SDK_VERSION = require('../package.json').version;
 const OFFLINE_REQUEST_FORMAT = 'licensekit-offline-request';
 const OFFLINE_LICENSE_FORMAT = 'licensekit-offline-license';
 const OFFLINE_DEACTIVATION_FORMAT = 'licensekit-offline-deactivation';
-const DEFINITIVE = new Set(['invalid_key', 'not_activated', 'license_suspended', 'license_revoked', 'license_expired', 'sdk_update_required', 'app_update_required', 'vm_not_allowed']);
+/** Refusals kept as the license's state: offline, the app keeps being told them. floating_license: the policy is floating, so the
+ * app must check out a seat (checkout) instead of activating. */
+const DEFINITIVE = new Set(['invalid_key', 'not_activated', 'license_suspended', 'license_revoked', 'license_expired', 'sdk_update_required', 'app_update_required', 'vm_not_allowed', 'floating_license']);
 /** The native hardware module. A non-literal require: bundlers leave it to Node, which must load the .node file from disk. */
 const HWID_PACKAGE = '@carchalabs/seal-hwid';
 /** Loads the native module once per process; null when it is not installed or has no build for this platform. */
@@ -35,6 +43,10 @@ function loadHwid() {
     }
     return hwidModule;
 }
+/** @internal for tests: the native module to use instead of the installed one (null: none). */
+function useHwidModule(module) {
+    hwidModule = module;
+}
 /**
  * The largest answer read, as in the native SDKs: a lease and its notices are a few kilobytes. A longer one is read as no
  * answer, so a broken or hostile server cannot make the app hold and parse hundreds of megabytes.
@@ -85,10 +97,14 @@ const CLOCK_MESSAGE = 'The date and time on this computer look wrong. Correct th
 class LicenseError extends Error {
     code;
     status;
-    constructor(code, message, status) {
+    details;
+    constructor(code, message, status, 
+    /** The refusal's other fields: for seats_exhausted, inUse, total and retryAfter (seconds); for rate_limited, retryAfter. */
+    details) {
         super(message);
         this.code = code;
         this.status = status;
+        this.details = details;
         this.name = 'LicenseError';
     }
 }
@@ -302,8 +318,13 @@ class Seal {
         }
         if (typeof json !== 'object' || json === null)
             json = {};
-        if (!res.ok)
-            throw new LicenseError(json.error ?? 'server_error', json.message ?? `License server error (${res.status})`, res.status);
+        if (!res.ok) {
+            const details = {};
+            for (const name of ['inUse', 'total', 'retryAfter', 'reason'])
+                if (json[name] !== undefined)
+                    details[name] = json[name];
+            throw new LicenseError(json.error ?? 'server_error', json.message ?? `License server error (${res.status})`, res.status, Object.keys(details).length ? details : undefined);
+        }
         return json;
     }
     emptyState(status, offline, extra = {}) {
@@ -311,17 +332,20 @@ class Seal {
     }
     /**
      * The device's public key, sent with activation and check-ins so the server wraps feature keys for
-     * this machine only. Only when the native module verifies for this app (it then also decrypts, with
-     * the matching secret it derives itself) and hardware is not turned off. Never throws.
+     * this machine only. Sent when the native module can also decrypt what is wrapped for it, with the
+     * matching secret it derives itself: through the compiled-in keys when they verify for this app, or,
+     * with seal-hwid 0.5+, through this app's own keys (every hosted vendor, a self-hosted server). Not
+     * with hardware turned off. Never throws.
      */
     deviceKey() {
         if (this.deviceKeyCache === undefined) {
             let key = null;
             try {
+                const hwid = this.opts.hardware === false ? null : loadHwid();
                 const native = this.opts.hardware === false ? null : this.native();
-                if (native && typeof native.devicePublicKey === 'function' && typeof native.decryptFeature === 'function') {
-                    key = native.devicePublicKey(`licensekit:${this.opts.product}`);
-                }
+                const decrypts = (native && typeof native.decryptFeature === 'function') || this.deviceDecrypter() !== null;
+                if (hwid && typeof hwid.devicePublicKey === 'function' && decrypts)
+                    key = hwid.devicePublicKey(`licensekit:${this.opts.product}`);
             }
             catch {
                 key = null;
@@ -330,6 +354,17 @@ class Seal {
         }
         return this.deviceKeyCache ? { devicePublicKey: this.deviceKeyCache } : {};
     }
+    /** The native module's decryption with this app's own keys (seal-hwid 0.5+), or null: older module, none, or hardware off. */
+    deviceDecrypter() {
+        if (this.opts.hardware === false)
+            return null;
+        const hwid = loadHwid();
+        return hwid && typeof hwid.decryptFeatureWithKeys === 'function' ? hwid : null;
+    }
+    /** This app's public keys as SPKI PEM, for the native module. */
+    keyPems() {
+        return [...this.keys.values()].map((key) => key.export({ type: 'spki', format: 'pem' }).toString());
+    }
     /**
      * The native verifier, used only when its compiled-in keys include every key this app was given:
      * an app that trusts other keys (a self-hosted server) is checked by the JavaScript verifier alone.
@@ -510,8 +545,9 @@ class Seal {
      * Decrypts data you encrypted for a feature (encryptForFeature in @carchalabs/seal-core, with the
      * feature's content key from the console). Works offline: it uses the saved lease, which must be valid
      * (or in its offline grace period), grant the feature and carry its key, and the saved license key.
-     * The native module does the work when it trusts this app's keys, so the content key never reaches
-     * JavaScript; without it the JavaScript implementation is used. Throws a LicenseError:
+     * When the lease is wrapped for this machine's device key, the native module does the work (with its
+     * compiled-in keys or, seal-hwid 0.5+, this app's keys), so the device secret and the content key never
+     * reach JavaScript; a lease wrapped for the license key alone is opened in JavaScript. Throws a LicenseError:
      * `unlicensed`, a lease failure reason, `clock_suspect`, `feature_not_licensed` or `decrypt_failed`.
      */
     async decrypt(feature, data) {
@@ -581,10 +617,27 @@ class Seal {
         const graceSeconds = state.status === 'grace' ? (claims?.grc ?? (this.opts.graceDays ?? DEFAULT_GRACE_DAYS) * 86400) : 0;
         const check = { product: this.opts.product, fingerprintHash, now: this.nowSec(), ...(graceSeconds ? { graceSeconds } : {}) };
         const native = this.native();
+        // A lease wrapped for this machine's device key (epk) opens only in the native module, which holds the device
+        // secret: through the compiled-in keys when they verify for this app, else through this app's keys (seal-hwid 0.5+).
+        const deviceBound = claims?.epk !== undefined;
+        const withKeys = deviceBound && !(native && typeof native.decryptFeature === 'function') ? this.deviceDecrypter() : null;
+        const pems = withKeys ? this.keyPems() : [];
         return (data) => {
-            const result = native && typeof native.decryptFeature === 'function'
-                ? native.decryptFeature(leased.token, check, leased.licenseKey, feature, Buffer.from(data))
-                : (0, seal_core_1.decryptFeature)(leased.token, { keys: this.keys, ...check }, leased.licenseKey, feature, Buffer.from(data));
+            let result;
+            if (native && typeof native.decryptFeature === 'function') {
+                result = native.decryptFeature(leased.token, check, leased.licenseKey, feature, Buffer.from(data));
+            }
+            else if (withKeys) {
+                try {
+                    result = withKeys.decryptFeatureWithKeys(leased.token, check, pems, leased.licenseKey, feature, Buffer.from(data));
+                }
+                catch {
+                    result = { ok: false, reason: 'decrypt_failed' };
+                }
+            }
+            else {
+                result = (0, seal_core_1.decryptFeature)(leased.token, { keys: this.keys, ...check }, leased.licenseKey, feature, Buffer.from(data));
+            }
             if (result.ok && result.data)
                 return Buffer.from(result.data);
             if (result.reason === 'not_licensed')
@@ -682,9 +735,149 @@ class Seal {
         }
         await this.clear();
     }
+    /**
+     * Floating licenses: takes a seat of the license's pool for as long as the app runs (server docs/floating.md). With a
+     * license key, uses it and saves it for the next checkout; without, uses the saved one. The Seat renews itself, emits
+     * 'renewed' and, when the seat cannot be kept, 'lost' with the reason; give it back with seat.release() (in
+     * Electron the SDK also does on quit, see releaseOnQuit). There is no offline grace: a seat needs the server. Throws a
+     * LicenseError: `unlicensed`, the server's refusal (seats_exhausted with details inUse, total and retryAfter,
+     * not_floating for a node-locked license, license_revoked, …), `network`, or a seat token failure reason.
+     */
+    checkout(licenseKey, options = {}) {
+        return this.checkoutNow(licenseKey, options);
+    }
+    async checkoutNow(licenseKey, options) {
+        const fingerprintHash = await this.fingerprint();
+        const key = licenseKey?.trim().toUpperCase() ?? (await this.load())?.licenseKey;
+        if (!key)
+            throw new LicenseError('unlicensed', 'Enter a license key to check out a seat.');
+        const host = this.seatHost(key, fingerprintHash, options);
+        const answer = await this.post('/v1/seats/checkout', await host.checkoutBody());
+        const held = (0, seat_1.acceptSeat)(host, answer, undefined, undefined);
+        if (typeof held === 'string')
+            throw new LicenseError(held, REASON_TEXT[held] ?? 'The license server sent an unusable seat.');
+        // The key is kept for the next checkout. A seat token never is: it lives in memory only.
+        if (licenseKey !== undefined) {
+            await this.serial(async () => {
+                if ((await this.load())?.licenseKey !== key)
+                    await this.save({ licenseKey: key });
+            });
+        }
+        const seat = new seat_1.Seat(host, held, options.renewAutomatically !== false, (s) => heldSeats.delete(s));
+        if (this.opts.releaseOnQuit !== false) {
+            heldSeats.add(seat);
+            installQuitRelease();
+        }
+        return seat;
+    }
+    seatHost(licenseKey, fingerprintHash, options) {
+        const monotonic = this.opts.monotonic ?? (() => performance.now());
+        return {
+            product: this.opts.product,
+            keys: this.keys,
+            fingerprintHash,
+            licenseKey,
+            post: (path, body) => this.post(path, body),
+            checkoutBody: async () => ({
+                licenseKey,
+                product: this.opts.product,
+                fingerprint: fingerprintHash,
+                machineName: options.machineName?.slice(0, 80),
+                platform: (0, node_os_1.platform)(),
+                appVersion: this.opts.appVersion,
+                sdkVersion: exports.SDK_VERSION,
+                ...(await this.hardware()),
+                ...this.seatDeviceKey(),
+                // Always sent: only a license that counts by process uses it.
+                instance: INSTANCE,
+                ...(options.user !== undefined ? { user: (0, node_crypto_1.createHash)('sha256').update(`licensekit-user:${this.opts.product}:${options.user}`, 'utf8').digest('base64url') } : {}),
+            }),
+            proof: (token, license) => {
+                const hwid = this.seatProver();
+                if (!hwid)
+                    return null;
+                try {
+                    return hwid.seatProof(token, { product: this.opts.product, fingerprintHash, license }, this.keyPems());
+                }
+                catch {
+                    return null;
+                }
+            },
+            monotonic,
+            wallMs: () => this.opts.now?.() ?? Date.now(),
+            isLicenseError: (e) => e instanceof LicenseError,
+        };
+    }
+    /** The native module's seat proof (seal-hwid 0.6+), or null: older module, none, or hardware off. */
+    seatProver() {
+        if (this.opts.hardware === false)
+            return null;
+        const hwid = loadHwid();
+        return hwid && typeof hwid.seatProof === 'function' && typeof hwid.devicePublicKey === 'function' ? hwid : null;
+    }
+    /**
+     * The device key a seat is bound to, only when the native module can prove it in every heartbeat: a seat bound to a
+     * key the app cannot prove could not be renewed. Never throws.
+     */
+    seatDeviceKey() {
+        try {
+            const key = this.seatProver()?.devicePublicKey(`licensekit:${this.opts.product}`);
+            return typeof key === 'string' ? { devicePublicKey: key } : {};
+        }
+        catch {
+            return {};
+        }
+    }
     static hasFeature(state, feature) {
         return (state.status === 'valid' || state.status === 'grace') && state.features.includes(feature);
     }
 }
 exports.Seal = Seal;
 exports.LicenseKit = Seal;
+/** This process's instance id for counting by process: the SHA-256 of 128 random bits, made once (spec section 4). */
+const INSTANCE = (0, node_crypto_1.createHash)('sha256').update((0, node_crypto_1.randomBytes)(16)).digest('base64url');
+/** Seats held by this process whose Seal releases them on quit. */
+const heldSeats = new Set();
+/** How long quitting waits for the releases. */
+const QUIT_RELEASE_MS = 2000;
+let quitHookInstalled = false;
+/**
+ * In Electron, gives held seats back when the app quits: on will-quit (all windows closed, so no window can still cancel
+ * the quit) the quit is held, the seats are released (at most 2 seconds), and the app exits with app.exit(0), which does
+ * not emit before-quit or will-quit again (Electron's app API). Not when another listener already prevented the quit, nor
+ * when no seat is held. On Windows, Electron emits no quit event at shutdown or logout; seats then free themselves when
+ * their tokens expire. @internal exported for tests; `app` is Electron's when not given.
+ */
+function installQuitRelease(app) {
+    if (quitHookInstalled)
+        return true;
+    if (!app) {
+        if (!process.versions.electron)
+            return false;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            app = require('electron').app;
+        }
+        catch {
+            return false;
+        }
+        if (!app)
+            return false;
+    }
+    quitHookInstalled = true;
+    const quitting = app;
+    quitting.on('will-quit', (event) => {
+        if (event.defaultPrevented || heldSeats.size === 0)
+            return;
+        event.preventDefault();
+        const releases = Promise.allSettled([...heldSeats].map((seat) => seat.release()));
+        const cap = new Promise((done) => setTimeout(done, QUIT_RELEASE_MS).unref?.());
+        void Promise.race([releases, cap]).finally(() => quitting.exit(0));
+    });
+    return true;
+}
+/** @internal for tests: forget the hook and the held seats. */
+function resetQuitRelease() {
+    quitHookInstalled = false;
+    heldSeats.clear();
+}

package/dist/seat.d.ts

@@ -0,0 +1,118 @@
+import { EventEmitter } from 'node:events';
+import { KeyObject } from 'node:crypto';
+import { LeaseFailure, SeatClaims } from '@carchalabs/seal-core';
+/** Raised for a refusal or a failure; the server's error code and message. */
+export interface SeatErrorLike {
+    code: string;
+    message: string;
+    status?: number;
+    details?: Record<string, unknown>;
+}
+/** What the Seal gives a Seat: its requests and its checks. Internal. */
+export interface SeatHost {
+    product: string;
+    keys: Map<string, KeyObject>;
+    fingerprintHash: string;
+    /** POST to the license server; throws a LicenseError. */
+    post(path: string, body: Record<string, unknown>): Promise<any>;
+    /** The checkout body (license key, fingerprint, hardware, device key, instance, user). */
+    checkoutBody(): Promise<Record<string, unknown>>;
+    licenseKey: string;
+    /** The proof for the next heartbeat or release of a device-bound token, from the native module; null when it has none. */
+    proof(token: string, license: string): {
+        ok: true;
+        seq: number;
+        proof: string;
+    } | {
+        ok: false;
+        reason: string;
+    } | null;
+    /** Milliseconds on a monotonic clock. */
+    monotonic(): number;
+    /** Milliseconds since the Unix epoch, for the times the Seat shows. */
+    wallMs(): number;
+    isLicenseError(e: unknown): e is SeatErrorLike;
+}
+export type SeatStatus = 'held' | 'lost' | 'released';
+/** Why a seat was lost: the server's refusal (license_revoked, seats_exhausted, …) or `expired` (no renewal in time). */
+export interface SeatLoss {
+    reason: string;
+    message: string;
+}
+/** A checked-out answer, verified. */
+interface Held {
+    token: string;
+    claims: SeatClaims;
+    /** Monotonic times (ms): when to renew, and when the seat ends without a renewal. */
+    renewAt: number;
+    deadline: number;
+    seats: {
+        inUse: number;
+        total: number | null;
+    };
+    license: {
+        id: string;
+        expiresAt: string | null;
+    };
+}
+/**
+ * Verifies a seat token from a checkout or heartbeat answer: the lease's checks with the seat type, then the license,
+ * the seat held and the next counter (spec section 2). Returns the held state, or the failure reason.
+ */
+export declare function acceptSeat(host: SeatHost, answer: any, license: string | undefined, held: {
+    sid: string;
+    seq: number;
+} | undefined): Held | LeaseFailure;
+export declare class Seat extends EventEmitter {
+    private readonly host;
+    private readonly automatic;
+    private readonly onEnd;
+    private current;
+    private state;
+    private loss?;
+    private timer?;
+    private retries;
+    /** The session is gone (seat_expired, seat_conflict, seat_not_found): the next attempt checks out again. */
+    private checkOutAgain;
+    /** Renewals and the release one at a time, in order. */
+    private queue;
+    /** @internal Made by Seal.checkout(). */
+    constructor(host: SeatHost, held: Held, automatic: boolean, onEnd: (seat: Seat) => void);
+    /** held, lost or released. */
+    get status(): SeatStatus;
+    /** Why the seat was lost; set when status is lost. */
+    get lostReason(): SeatLoss | undefined;
+    /** The session's id; a new one after the SDK checked out again on the same seat. */
+    get id(): string;
+    get features(): string[];
+    has(feature: string): boolean;
+    /** Seats in use and the pool's size (null: unlimited), as of the last answer. */
+    get seats(): {
+        inUse: number;
+        total: number | null;
+    };
+    get license(): {
+        id: string;
+        expiresAt: string | null;
+    };
+    /** When the seat ends if no renewal succeeds before (from the monotonic deadline, shown in this computer's time). */
+    get expiresAt(): string;
+    /** Renews now. The Seat does this itself before the token's renewal time, unless checked out with renewAutomatically: false. */
+    renew(): Promise<SeatStatus>;
+    /**
+     * Gives the seat back; the server frees it at once. Resolves true when the server confirmed it, false when it could
+     * not be reached (the seat then frees itself when its token expires). The Seat is released either way.
+     */
+    release(): Promise<boolean>;
+    private serial;
+    private schedule;
+    private end;
+    private lose;
+    /** The next heartbeat's or release's body: the counter, the current token's id and, for a device-bound seat, the proof. */
+    private next;
+    private renewNow;
+    /** Tries again later, never past the deadline (the timer then ends the seat). retryAfter: the server's, in seconds. */
+    private retry;
+    private releaseNow;
+}
+export {};

package/dist/seat.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Seat = void 0;
+exports.acceptSeat = acceptSeat;
+// Seats for floating licenses (server docs/floating.md): a seat is held only while the app runs. seal.checkout()
+// takes one; the Seat renews itself before its token's renewal time and gives it back with release(). The seat token
+// lives in memory only. There is no offline grace: when renewals fail, the seat ends at its deadline, measured on a
+// monotonic clock from when the token arrived, so the device's clock cannot extend it. When the seat is lost the Seat
+// emits 'lost' with the reason and does nothing else (the app decides what to do).
+const node_events_1 = require("node:events");
+const seal_core_1 = require("@carchalabs/seal-core");
+/** Retries of a renewal that got no answer: 15 s, then 30 s, then every 60 s, never past the deadline. */
+const RETRY_MS = [15_000, 30_000, 60_000];
+/** Answers that mean the session is gone or was taken over: check out again (spec sections 3 and 6). */
+const CHECK_OUT_AGAIN = new Set(['seat_expired', 'seat_conflict', 'seat_not_found']);
+/** No usable answer: try again before the deadline. Every other refusal ends the seat. */
+const TRANSIENT = new Set(['network', 'server_error', 'rate_limited']);
+/** A 2xx whose token fails for one of these did not come from this app's server for this device (as for leases). */
+const NOT_A_TOKEN_FOR_THIS_DEVICE = new Set(['malformed', 'unsupported_algorithm', 'wrong_type', 'unknown_key', 'bad_signature', 'wrong_issuer', 'wrong_product', 'wrong_device']);
+const SEAT_TEXT = {
+    expired: 'The license server could not be reached in time, so the seat was given back. Connect to the internet and check out again.',
+    device_proof_unavailable: "This seat is bound to this computer's device key, which could not be read. Check out again.",
+};
+/**
+ * Verifies a seat token from a checkout or heartbeat answer: the lease's checks with the seat type, then the license,
+ * the seat held and the next counter (spec section 2). Returns the held state, or the failure reason.
+ */
+function acceptSeat(host, answer, license, held) {
+    const token = typeof answer?.token === 'string' ? answer.token : '';
+    const licenseId = license ?? (typeof answer?.license?.id === 'string' ? answer.license.id : '');
+    const r = (0, seal_core_1.verifySeat)(token, { keys: host.keys, product: host.product, fingerprintHash: host.fingerprintHash, license: licenseId, ...(held ? { held } : {}) });
+    if (!r.ok)
+        return r.reason;
+    const arrived = host.monotonic();
+    const { iat, rev, exp } = r.claims;
+    const total = answer?.seats?.total;
+    return {
+        token,
+        claims: r.claims,
+        renewAt: arrived + (rev - iat) * 1000,
+        deadline: arrived + (exp - iat) * 1000,
+        seats: { inUse: Number.isInteger(answer?.seats?.inUse) ? answer.seats.inUse : 0, total: Number.isInteger(total) ? total : null },
+        license: { id: r.claims.sub, expiresAt: r.claims.lxp === undefined ? null : new Date(r.claims.lxp * 1000).toISOString() },
+    };
+}
+class Seat extends node_events_1.EventEmitter {
+    host;
+    automatic;
+    onEnd;
+    current;
+    state = 'held';
+    loss;
+    timer;
+    retries = 0;
+    /** The session is gone (seat_expired, seat_conflict, seat_not_found): the next attempt checks out again. */
+    checkOutAgain = false;
+    /** Renewals and the release one at a time, in order. */
+    queue = Promise.resolve();
+    /** @internal Made by Seal.checkout(). */
+    constructor(host, held, automatic, onEnd) {
+        super();
+        this.host = host;
+        this.automatic = automatic;
+        this.onEnd = onEnd;
+        this.current = held;
+        this.schedule();
+    }
+    /** held, lost or released. */
+    get status() {
+        return this.state;
+    }
+    /** Why the seat was lost; set when status is lost. */
+    get lostReason() {
+        return this.loss;
+    }
+    /** The session's id; a new one after the SDK checked out again on the same seat. */
+    get id() {
+        return this.current.claims.sid;
+    }
+    get features() {
+        return [...this.current.claims.feat];
+    }
+    has(feature) {
+        return this.state === 'held' && this.current.claims.feat.includes(feature);
+    }
+    /** Seats in use and the pool's size (null: unlimited), as of the last answer. */
+    get seats() {
+        return { ...this.current.seats };
+    }
+    get license() {
+        return { ...this.current.license };
+    }
+    /** When the seat ends if no renewal succeeds before (from the monotonic deadline, shown in this computer's time). */
+    get expiresAt() {
+        return new Date(this.host.wallMs() + Math.max(0, this.current.deadline - this.host.monotonic())).toISOString();
+    }
+    /** Renews now. The Seat does this itself before the token's renewal time, unless checked out with renewAutomatically: false. */
+    renew() {
+        return this.serial(() => this.renewNow());
+    }
+    /**
+     * Gives the seat back; the server frees it at once. Resolves true when the server confirmed it, false when it could
+     * not be reached (the seat then frees itself when its token expires). The Seat is released either way.
+     */
+    release() {
+        return this.serial(() => this.releaseNow());
+    }
+    serial(operation) {
+        const run = this.queue.then(operation);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    schedule(at) {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.state !== 'held' || !this.automatic)
+            return;
+        const when = Math.min(at ?? this.current.renewAt, this.current.deadline);
+        // A held seat never keeps the process alive: when it ends without release(), the seat frees itself at its expiry.
+        this.timer = setTimeout(() => void this.renew(), Math.max(0, when - this.host.monotonic()));
+        this.timer.unref?.();
+    }
+    end(state, loss) {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.state = state;
+        this.onEnd(this);
+        if (loss) {
+            this.loss = loss;
+            this.emit('lost', loss);
+        }
+    }
+    lose(reason, message) {
+        this.end('lost', { reason, message: message ?? SEAT_TEXT[reason] ?? 'The seat was lost.' });
+        return this.state;
+    }
+    /** The next heartbeat's or release's body: the counter, the current token's id and, for a device-bound seat, the proof. */
+    next() {
+        const { claims, token } = this.current;
+        const body = { licenseKey: this.host.licenseKey, product: this.host.product, seq: claims.seq + 1, tokenId: claims.jti };
+        if (claims.sep === undefined)
+            return body;
+        const proof = this.host.proof(token, claims.sub);
+        if (!proof || !proof.ok || proof.seq !== claims.seq + 1)
+            return null;
+        return { ...body, proof: proof.proof };
+    }
+    async renewNow() {
+        if (this.state !== 'held')
+            return this.state;
+        if (this.host.monotonic() >= this.current.deadline)
+            return this.lose('expired');
+        let answer;
+        let accepted;
+        try {
+            if (this.checkOutAgain) {
+                answer = await this.host.post('/v1/seats/checkout', await this.host.checkoutBody());
+                accepted = acceptSeat(this.host, answer, this.current.claims.sub, undefined);
+            }
+            else {
+                const body = this.next();
+                if (!body)
+                    return this.lose('device_proof_unavailable');
+                answer = await this.host.post(`/v1/seats/${encodeURIComponent(this.current.claims.sid)}/heartbeat`, body);
+                accepted = acceptSeat(this.host, answer, this.current.claims.sub, { sid: this.current.claims.sid, seq: this.current.claims.seq });
+            }
+        }
+        catch (e) {
+            if (!this.host.isLicenseError(e))
+                throw e;
+            if (this.state !== 'held')
+                return this.state;
+            if (CHECK_OUT_AGAIN.has(e.code) && !this.checkOutAgain) {
+                // The session ended or another copy renewed it (a lost answer, spec section 3): the same holder checks out
+                // again and keeps its seat.
+                this.checkOutAgain = true;
+                return this.renewNow();
+            }
+            if (TRANSIENT.has(e.code) || (e.status !== undefined && e.status >= 500))
+                return this.retry(e.code === 'rate_limited' ? Number(e.details?.retryAfter) : undefined);
+            return this.lose(e.code, e.message);
+        }
+        if (this.state !== 'held')
+            return this.state;
+        if (typeof accepted === 'string') {
+            // A 2xx without a seat token from this server for this device (a proxy's page): as no answer.
+            if (NOT_A_TOKEN_FOR_THIS_DEVICE.has(accepted))
+                return this.retry();
+            return this.lose(accepted);
+        }
+        this.current = accepted;
+        this.checkOutAgain = false;
+        this.retries = 0;
+        this.schedule();
+        this.emit('renewed', this);
+        return this.state;
+    }
+    /** Tries again later, never past the deadline (the timer then ends the seat). retryAfter: the server's, in seconds. */
+    retry(retryAfterSeconds) {
+        const wait = Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0 ? retryAfterSeconds * 1000 : RETRY_MS[Math.min(this.retries, RETRY_MS.length - 1)];
+        this.retries++;
+        this.schedule(this.host.monotonic() + wait);
+        return this.state;
+    }
+    async releaseNow() {
+        if (this.state !== 'held')
+            return this.state === 'released';
+        const body = this.checkOutAgain ? null : this.next();
+        // Ended here first: a renewal timer must not run while the release is on its way.
+        this.end('released');
+        if (!body)
+            return false;
+        try {
+            await this.host.post(`/v1/seats/${encodeURIComponent(this.current.claims.sid)}/release`, body);
+            return true;
+        }
+        catch (e) {
+            if (!this.host.isLicenseError(e))
+                throw e;
+            // Already gone: nothing is held on the server.
+            return e.code === 'seat_expired' || e.code === 'seat_not_found';
+        }
+    }
+}
+exports.Seat = Seat;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carchalabs/seal-electron",
-  "version": "0.6.2",
-  "description": "Carcha Seal (formerly LicenseKit) SDK for the Electron main process and Node: activation, offline verification, grace period",
+  "version": "0.8.0",
+  "description": "Carcha Seal SDK for the Electron main process and Node: activation, offline verification, grace period",
   "keywords": ["electron", "licensing", "license-key", "software-licensing", "offline-licensing", "node-locked", "ed25519", "jws", "carcha-seal"],
   "homepage": "https://seal.carchalabs.com/docs/",
   "repository": { "type": "git", "url": "git+https://github.com/carcha-labs/carcha-seal-sdk.git", "directory": "packages/sdk-electron" },
@@ -15,10 +15,10 @@
     "test": "node --no-warnings=ExperimentalWarning --test dist/*.test.js"
   },
   "dependencies": {
-    "@carchalabs/seal-core": "0.5.1"
+    "@carchalabs/seal-core": "0.6.0"
   },
   "optionalDependencies": {
-    "@carchalabs/seal-hwid": "0.4.1"
+    "@carchalabs/seal-hwid": "0.6.0"
   },
   "engines": { "node": ">=22.13" },
   "publishConfig": { "access": "public" },