@carchalabs/seal-electron 0.6.1 → 0.7.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');

package/dist/index.d.ts

@@ -80,6 +80,8 @@ export declare class Seal {
     /** The native lease verifier, when it trusts every key this app was given (undefined = not looked up yet). */
     private nativeLease?;
     private deviceKeyCache?;
+    /** The end of the operations waiting to run; see serial(). */
+    private queue;
     constructor(opts: SealOptions);
     private get fetch();
     private nowSec;
@@ -89,18 +91,31 @@ export declare class Seal {
     private hardware;
     /** The saved record; null when there is none, or it cannot be read or is not a record (as no license). */
     private load;
-    /** Replaces license.dat whole: written to license.dat.tmp, then renamed over it, so a crash or full disk mid-write
-     * leaves the previous record. */
+    /** Replaces license.dat whole: written to a temporary file of this save, then renamed over it, so a crash or full disk
+     * mid-write leaves the previous record. */
     private save;
     private clear;
+    /**
+     * Runs the operations that change license.dat one at a time, in the order they were called, as the native SDKs' lock
+     * does. Node.js calls writing one file from calls that overlap unsafe, and the answer to an earlier call (a slow
+     * check-in for the old key) must not replace what a later one saved (an activation with a new key). Reads
+     * (decrypt, requireEncrypted) do not wait: the file is replaced whole, so a read sees one record or the other.
+     */
+    private serial;
     private post;
     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.
@@ -115,15 +130,18 @@ export declare class Seal {
     private stateFromLease;
     /** machineName: the name to show the vendor for this device. Nothing is sent when the app gives none (host names often hold a person's name). */
     activate(licenseKey: string, machineName?: string): Promise<LicenseState>;
+    private activateNow;
     check(): Promise<LicenseState>;
+    private checkNow;
     /** The state from the saved record when the server gave no usable answer; a usable lease moves lastSeen forward. */
     private offlineCheck;
     /**
      * 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>;
@@ -158,13 +176,16 @@ export declare class Seal {
      * LicenseError: `invalid_file`, `wrong_product`, or a lease failure reason such as `wrong_device`.
      */
     activateOffline(licenseFile: string): Promise<LicenseState>;
+    private activateOfflineNow;
     /**
      * Gives an offline machine's seat back: removes the license from this device and returns the
      * deactivation file (JSON text) for the vendor, who frees the seat by uploading it in the console.
      * Throws `unlicensed` when there is no license to remove.
      */
     deactivateOffline(): Promise<string>;
+    private deactivateOfflineNow;
     deactivate(): Promise<void>;
+    private deactivateNow;
     static hasFeature(state: LicenseState, feature: string): boolean;
 }
 /** The SDK class under its earlier name (LicenseKit). Same class; use Seal in new code. */

package/dist/index.js

@@ -35,11 +35,44 @@ function loadHwid() {
     }
     return hwidModule;
 }
+/**
+ * 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.
+ */
+const MAX_ANSWER_BYTES = 1 << 20;
+/** The answer's body as text; null when it is longer than MAX_ANSWER_BYTES or could not be read to its end. */
+async function readLimited(res) {
+    const declared = Number(res.headers.get('content-length') ?? NaN);
+    if (declared > MAX_ANSWER_BYTES || !res.body) {
+        await res.body?.cancel().catch(() => { });
+        return res.body ? null : '';
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > MAX_ANSWER_BYTES) {
+                await reader.cancel().catch(() => { });
+                return null;
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        return null;
+    }
+    // UTF-8 as response.json() decodes it (a byte order mark dropped).
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+/** Numbers this process's temporary files (see Seal.save). */
+let tempCounter = 0;
 /** The server accepts at most this many components. */
 const MAX_COMPONENTS = 32;
-/** The license itself is gone: forget the key too. The other refusals can be undone on the server (resume, renew,
- *  re-activate), so the key is kept and the next successful online check restores the license on its own. */
-const FORGET_KEY = new Set(['invalid_key', 'license_revoked']);
 const CLOCK_TOLERANCE_SECONDS = 24 * 3600;
 /**
  * A check-in answered 2xx whose lease fails for one of these reasons did not come from this app's license server for
@@ -128,6 +161,8 @@ class Seal {
     /** The native lease verifier, when it trusts every key this app was given (undefined = not looked up yet). */
     nativeLease;
     deviceKeyCache;
+    /** The end of the operations waiting to run; see serial(). */
+    queue = Promise.resolve();
     constructor(opts) {
         this.opts = opts;
         checkServerUrl(opts.serverUrl);
@@ -191,24 +226,53 @@ class Seal {
             return null;
         }
     }
-    /** Replaces license.dat whole: written to license.dat.tmp, then renamed over it, so a crash or full disk mid-write
-     * leaves the previous record. */
+    /** Replaces license.dat whole: written to a temporary file of this save, then renamed over it, so a crash or full disk
+     * mid-write leaves the previous record. */
     async save(stored) {
         await (0, promises_1.mkdir)(this.opts.storageDir, { recursive: true });
         const text = JSON.stringify(stored);
-        const temp = this.file + '.tmp';
-        try {
-            await (0, promises_1.writeFile)(temp, this.opts.secureStore ? await this.opts.secureStore.encrypt(text) : text, { mode: 0o600, flush: true });
-            await (0, promises_1.rename)(temp, this.file);
-        }
-        catch (e) {
-            await (0, promises_1.rm)(temp, { force: true }).catch(() => { });
-            throw e;
+        const data = this.opts.secureStore ? await this.opts.secureStore.encrypt(text) : text;
+        // license.dat.<pid>.<n>.tmp, created only if it does not exist (flag wx; SEI CERT FIO21-C: a unique name, opened
+        // exclusively, owner-only), so two app instances saving at the same time each write and rename their own file.
+        // A name left by a process that crashed is skipped.
+        for (let attempt = 0;; attempt++) {
+            const temp = `${this.file}.${process.pid}.${tempCounter++}.tmp`;
+            try {
+                await (0, promises_1.writeFile)(temp, data, { mode: 0o600, flush: true, flag: 'wx' });
+            }
+            catch (e) {
+                if (e.code === 'EEXIST') {
+                    if (attempt < 100)
+                        continue; // another file's name: not ours to remove
+                    throw e;
+                }
+                await (0, promises_1.rm)(temp, { force: true }).catch(() => { }); // ours, cut off mid-write
+                throw e;
+            }
+            try {
+                await (0, promises_1.rename)(temp, this.file);
+                return;
+            }
+            catch (e) {
+                await (0, promises_1.rm)(temp, { force: true }).catch(() => { });
+                throw e;
+            }
         }
     }
     async clear() {
         await (0, promises_1.rm)(this.file, { force: true });
     }
+    /**
+     * Runs the operations that change license.dat one at a time, in the order they were called, as the native SDKs' lock
+     * does. Node.js calls writing one file from calls that overlap unsafe, and the answer to an earlier call (a slow
+     * check-in for the old key) must not replace what a later one saved (an activation with a new key). Reads
+     * (decrypt, requireEncrypted) do not wait: the file is replaced whole, so a read sees one record or the other.
+     */
+    serial(operation) {
+        const run = this.queue.then(operation);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
     async post(path, body) {
         let res;
         try {
@@ -225,7 +289,19 @@ class Seal {
         catch {
             throw new LicenseError('network', 'Could not reach the license server.');
         }
-        const json = await res.json().catch(() => ({}));
+        const text = await readLimited(res);
+        // Longer than the limit, or cut off (the timeout, a broken connection): no answer, as in the native SDKs.
+        if (text === null)
+            throw new LicenseError('network', 'Could not reach the license server.');
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            json = {};
+        }
+        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);
         return json;
@@ -235,17 +311,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;
@@ -254,6 +333,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.
@@ -334,7 +424,10 @@ class Seal {
         return this.emptyState('invalid', offline, { reason: strict.reason, message: REASON_TEXT[strict.reason], keyHint });
     }
     /** machineName: the name to show the vendor for this device. Nothing is sent when the app gives none (host names often hold a person's name). */
-    async activate(licenseKey, machineName) {
+    activate(licenseKey, machineName) {
+        return this.serial(() => this.activateNow(licenseKey, machineName));
+    }
+    async activateNow(licenseKey, machineName) {
         const fingerprint = await this.fingerprint();
         const key = licenseKey.trim().toUpperCase();
         const response = await this.post('/v1/activate', {
@@ -355,7 +448,10 @@ class Seal {
         await this.save(stored);
         return state;
     }
-    async check() {
+    check() {
+        return this.serial(() => this.checkNow());
+    }
+    async checkNow() {
         try {
             await this.fingerprint();
         }
@@ -390,11 +486,11 @@ class Seal {
         }
         catch (e) {
             if (e instanceof LicenseError && DEFINITIVE.has(e.code)) {
-                // Persist the refusal: drop the signed lease so going offline cannot bring the license back.
-                if (FORGET_KEY.has(e.code))
-                    await this.clear();
-                else
-                    await this.save({ licenseKey: stored.licenseKey, lastSeen: stored.lastSeen, refused: { code: e.code, message: e.message, at: this.nowSec() } });
+                // Persist the refusal: drop the signed lease so going offline cannot bring the license back. The key is kept, also
+                // for invalid_key and license_revoked: a refusal is not signed, so anything that answers on the connection (a
+                // TLS-inspecting proxy) could send one, and the next check-in the server answers with a lease restores the
+                // license. A refusal that is real stays one: the server refuses the kept key again.
+                await this.save({ licenseKey: stored.licenseKey, lastSeen: stored.lastSeen, refused: { code: e.code, message: e.message, at: this.nowSec() } });
                 const keyHint = `${stored.licenseKey.slice(0, 7)}…${stored.licenseKey.slice(-4)}`;
                 return this.emptyState('invalid', false, { reason: e.code, message: e.message, keyHint });
             }
@@ -428,8 +524,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) {
@@ -499,10 +596,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')
@@ -539,7 +653,10 @@ class Seal {
      * check() works without the server until the lease's renewal date plus the offline grace. Throws a
      * LicenseError: `invalid_file`, `wrong_product`, or a lease failure reason such as `wrong_device`.
      */
-    async activateOffline(licenseFile) {
+    activateOffline(licenseFile) {
+        return this.serial(() => this.activateOfflineNow(licenseFile));
+    }
+    async activateOfflineNow(licenseFile) {
         await this.fingerprint();
         let file;
         try {
@@ -566,14 +683,20 @@ class Seal {
      * deactivation file (JSON text) for the vendor, who frees the seat by uploading it in the console.
      * Throws `unlicensed` when there is no license to remove.
      */
-    async deactivateOffline() {
+    deactivateOffline() {
+        return this.serial(() => this.deactivateOfflineNow());
+    }
+    async deactivateOfflineNow() {
         const stored = await this.load();
         if (!stored?.token)
             throw new LicenseError('unlicensed', 'This device has no license.');
         await this.clear();
         return JSON.stringify({ format: OFFLINE_DEACTIVATION_FORMAT, version: 1, product: this.opts.product, token: stored.token }, null, 2);
     }
-    async deactivate() {
+    deactivate() {
+        return this.serial(() => this.deactivateNow());
+    }
+    async deactivateNow() {
         const stored = await this.load();
         if (!stored)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carchalabs/seal-electron",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Carcha Seal (formerly LicenseKit) 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/",
@@ -18,7 +18,7 @@
     "@carchalabs/seal-core": "0.5.1"
   },
   "optionalDependencies": {
-    "@carchalabs/seal-hwid": "0.4.1"
+    "@carchalabs/seal-hwid": "0.5.0"
   },
   "engines": { "node": ">=22.13" },
   "publishConfig": { "access": "public" },