@carchalabs/seal-electron 0.8.0 → 0.9.0

package/README.md

@@ -23,6 +23,8 @@ if (Seal.hasFeature(state, 'export-pdf')) exportPdf();
 
 `check()` returns one of `valid`, `grace`, `invalid`, `unlicensed` or `clock_suspect`, with `offline` and `storageProtected` flags. A refusal from the server (suspended, expired, device removed, update required) is kept while offline and cleared by the next successful check-in. `notices` carries what the server asks your app to act on, such as `sdk_update_recommended` or `app_update_recommended` with a `minimum` version and a `requiredFrom` date; the SDK shows nothing itself. `activate(key, machineName)` sends the device name you pass, and none when you pass nothing (a computer's host name often holds its user's name). `deactivate()` releases the seat.
 
+A saved license that is there and cannot be read (your `secureStore` cannot decrypt it, the file is damaged, or it is not a license record) is not `unlicensed`: `check()` answers `invalid` with `reason: 'storage_unreadable'`, and `deactivate()`, `deactivateOffline()`, `decrypt()` and a `checkout()` without a key throw that code. Nothing is removed. Ask for the license key again (`activate`), or have the offline license file loaded again (`activateOffline`): either replaces the record. A save is read back through your `secureStore` before it replaces the previous record; if what was written cannot be read back, the call throws `storage_error` and the previous record stays.
+
 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:
@@ -41,7 +43,7 @@ Computers that never reach the server use offline activation: `offlineRequest(ke
 
 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.
+**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` the SDK sends the computer's device key, the server wraps the feature keys for it, and the native module does the decryption: the content key never reaches JavaScript, and a copied `license.dat` opens nothing on another computer. A lease wrapped for the license key alone (no `seal-hwid` build for the platform, `hardware: false`, or a lease from before the device key was sent) is opened in JavaScript, where the content key can be read. `requireNativeDecrypt: true` refuses that case: `decrypt` and `requireEncrypted` then throw `hardware_required`. On the server, a policy with `featureKeyDeviceProof: required` sends no feature keys to a device without a device key.
 
 **Hardware components.** When `@carchalabs/seal-hwid` is installed, the SDK also sends one keyed hash per hardware part (motherboard, disk, network card, OS install, CPU and graphics models) and whether the computer is a virtual machine. The license server then recognises the computer after a new disk, network card or operating system install, and refuses a copied disk or system image on other hardware. Raw serial numbers never leave the computer. Without the package, or on a platform it has no module for, nothing extra is sent. `hardware: false` turns it off. Bundlers must leave the package to Node (mark it external); electron-builder unpacks its native module from the asar archive.
 

package/dist/index.d.ts

@@ -20,6 +20,10 @@ export interface LicenseState {
     status: LicenseStatus;
     offline: boolean;
     storageProtected: boolean;
+    /**
+     * Why the status is what it is: a lease failure, the server's refusal, or `storage_unreadable` (status `invalid`):
+     * a saved license is there and cannot be read, so ask for the key again or load the offline license file again.
+     */
     reason?: string;
     message?: string;
     customer?: string;
@@ -67,6 +71,15 @@ export interface SealOptions {
      * sent when it is not (or cannot load on this platform). false: never send them. A function: your own.
      */
     hardware?: false | (() => HardwareReport | null | Promise<HardwareReport | null>);
+    /**
+     * Decrypt feature data only when the lease's feature keys are wrapped for this machine's device key and the native
+     * module opens them, so neither the device secret nor the content key reaches JavaScript and a copied license.dat
+     * opens nothing. Default false: a lease wrapped for the license key alone (no native module for this platform,
+     * `hardware: false`, or a server that issued it before the device key was sent) is opened in JavaScript, as before.
+     * true: decrypt and requireEncrypted throw `hardware_required` instead. The server's policy setting
+     * featureKeyDeviceProof: required is what keeps such keys off devices without a device key.
+     */
+    requireNativeDecrypt?: boolean;
     now?: () => number;
     /** Milliseconds on a monotonic clock, for how long a seat lasts (default performance.now). For tests. */
     monotonic?: () => number;
@@ -115,10 +128,16 @@ export declare class Seal {
     fingerprint(): Promise<string>;
     /** Read once per instance: hardware does not change while the app runs. Never throws. */
     private hardware;
-    /** The saved record; null when there is none, or it cannot be read or is not a record (as no license). */
+    /**
+     * The saved record; null when there is none. A license.dat that is there and cannot be read (the secure store cannot
+     * decrypt it, it is damaged, or it is not a record) is not "no license": this throws `storage_unreadable`, so a
+     * licensed user is not shown a first-run screen. A new activation replaces the file.
+     */
     private load;
-    /** 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. */
+    /** The saved record, or null when there is none or it cannot be read: for a step that is about to replace it. */
+    private loadIfReadable;
+    /** Replaces license.dat whole: written to a temporary file of this save, read back, then renamed over it, so a crash,
+     * a full disk mid-write or a secure store that cannot decrypt what it encrypted leaves the previous record. */
     private save;
     private clear;
     /**
@@ -167,8 +186,9 @@ export declare class Seal {
      * (or in its offline grace period), grant the feature and carry its key, and the saved license key.
      * 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`.
+     * reach JavaScript; a lease wrapped for the license key alone is opened in JavaScript, or, with requireNativeDecrypt,
+     * refused (`hardware_required`). Throws a LicenseError: `unlicensed`, `storage_unreadable`, a lease failure reason, `clock_suspect`,
+     * `feature_not_licensed`, `hardware_required` or `decrypt_failed`.
      */
     decrypt(feature: string, data: Uint8Array): Promise<Buffer>;
     /**
@@ -188,6 +208,8 @@ export declare class Seal {
      * uses it once, requireEncrypted for a module and the encrypted modules it requires.
      */
     private opener;
+    /** What keeps this app from sending a device key. */
+    private deviceKeyHint;
     /**
      * Offline activation, step 1 on a machine that cannot reach the server: the request file (JSON text)
      * the user takes to a connected device. The license server turns it into a license file at
@@ -206,7 +228,8 @@ export declare class Seal {
     /**
      * 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.
+     * Throws `unlicensed` when there is no license to remove, and `storage_unreadable` when the saved one cannot be read
+     * (nothing is removed).
      */
     deactivateOffline(): Promise<string>;
     private deactivateOfflineNow;
@@ -217,7 +240,7 @@ export declare class Seal {
      * 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,
+     * LicenseError: `unlicensed`, `storage_unreadable` (no key given and the saved one cannot be read), 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>;

package/dist/index.js

@@ -129,6 +129,8 @@ function checkServerUrl(serverUrl) {
         return;
     throw new LicenseError('insecure_server_url', 'serverUrl must start with https:// (http:// only for localhost).');
 }
+/** A saved license that is there and cannot be read (storage_unreadable): what the user can do about it. */
+const STORAGE_UNREADABLE_MESSAGE = 'The saved license on this computer cannot be read. Enter your license key again, or load your offline license file again.';
 const REASON_TEXT = {
     malformed: 'The saved license is damaged. Please activate again.',
     bad_signature: 'The saved license was modified. Please activate again.',
@@ -231,19 +233,46 @@ class Seal {
         })();
         return this.hardwareCache.then((report) => report && report.components.length ? { components: report.components.slice(0, MAX_COMPONENTS), vm: report.vm === true } : {});
     }
-    /** The saved record; null when there is none, or it cannot be read or is not a record (as no license). */
+    /**
+     * The saved record; null when there is none. A license.dat that is there and cannot be read (the secure store cannot
+     * decrypt it, it is damaged, or it is not a record) is not "no license": this throws `storage_unreadable`, so a
+     * licensed user is not shown a first-run screen. A new activation replaces the file.
+     */
     async load() {
+        let buf;
+        try {
+            buf = await (0, promises_1.readFile)(this.file);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw new LicenseError('storage_unreadable', STORAGE_UNREADABLE_MESSAGE);
+        }
+        let stored = null;
         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 parseStored(JSON.parse(text));
+            stored = parseStored(JSON.parse(text));
         }
         catch {
-            return null;
+            stored = null;
+        }
+        if (!stored)
+            throw new LicenseError('storage_unreadable', STORAGE_UNREADABLE_MESSAGE);
+        return stored;
+    }
+    /** The saved record, or null when there is none or it cannot be read: for a step that is about to replace it. */
+    async loadIfReadable() {
+        try {
+            return await this.load();
+        }
+        catch (e) {
+            if (e instanceof LicenseError && e.code === 'storage_unreadable')
+                return null;
+            throw e;
         }
     }
-    /** 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. */
+    /** Replaces license.dat whole: written to a temporary file of this save, read back, then renamed over it, so a crash,
+     * a full disk mid-write or a secure store that cannot decrypt what it encrypted leaves the previous record. */
     async save(stored) {
         await (0, promises_1.mkdir)(this.opts.storageDir, { recursive: true });
         const text = JSON.stringify(stored);
@@ -265,6 +294,17 @@ class Seal {
                 await (0, promises_1.rm)(temp, { force: true }).catch(() => { }); // ours, cut off mid-write
                 throw e;
             }
+            try {
+                // Read back through the same path load() takes, before the previous record is replaced.
+                const back = await (0, promises_1.readFile)(temp);
+                const readBack = this.opts.secureStore ? await this.opts.secureStore.decrypt(back) : back.toString('utf8');
+                if (readBack !== text)
+                    throw new Error('read back differs');
+            }
+            catch {
+                await (0, promises_1.rm)(temp, { force: true }).catch(() => { });
+                throw new LicenseError('storage_error', 'The license could not be saved: what was written could not be read back.');
+            }
             try {
                 await (0, promises_1.rename)(temp, this.file);
                 return;
@@ -482,7 +522,16 @@ class Seal {
                 return this.emptyState('invalid', false, { reason: e.code, message: e.message });
             throw e;
         }
-        const stored = await this.load();
+        let stored;
+        try {
+            stored = await this.load();
+        }
+        catch (e) {
+            // Not "unlicensed": the app shows this to a customer who has a license, and nothing is changed on disk.
+            if (e instanceof LicenseError && e.code === 'storage_unreadable')
+                return this.emptyState('invalid', false, { reason: e.code, message: e.message });
+            throw e;
+        }
         if (!stored)
             return this.emptyState('unlicensed', false);
         if (stored.offline && stored.token) {
@@ -547,8 +596,9 @@ class Seal {
      * (or in its offline grace period), grant the feature and carry its key, and the saved license key.
      * 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`.
+     * reach JavaScript; a lease wrapped for the license key alone is opened in JavaScript, or, with requireNativeDecrypt,
+     * refused (`hardware_required`). Throws a LicenseError: `unlicensed`, `storage_unreadable`, a lease failure reason, `clock_suspect`,
+     * `feature_not_licensed`, `hardware_required` or `decrypt_failed`.
      */
     async decrypt(feature, data) {
         return (await this.opener(feature))(data);
@@ -622,7 +672,15 @@ class Seal {
         const deviceBound = claims?.epk !== undefined;
         const withKeys = deviceBound && !(native && typeof native.decryptFeature === 'function') ? this.deviceDecrypter() : null;
         const pems = withKeys ? this.keyPems() : [];
+        const nativeDecrypts = !!(native && typeof native.decryptFeature === 'function') || withKeys !== null;
         return (data) => {
+            // A feature the lease grants and carries a key for, which this app would open in JavaScript.
+            const carried = !!claims?.feat.includes(feature) && typeof claims.fk?.[feature] === 'string';
+            if (this.opts.requireNativeDecrypt && carried && !(deviceBound && nativeDecrypts)) {
+                throw new LicenseError('hardware_required', deviceBound
+                    ? `"${feature}" is wrapped for this computer's device key, but the native module that opens it (@carchalabs/seal-hwid) is not available here.`
+                    : `"${feature}" was sent for the license key alone, not for this computer's device key, and this app decrypts only device-bound keys (requireNativeDecrypt). ${this.deviceKeyHint()}`);
+            }
             let result;
             if (native && typeof native.decryptFeature === 'function') {
                 result = native.decryptFeature(leased.token, check, leased.licenseKey, feature, Buffer.from(data));
@@ -647,6 +705,16 @@ class Seal {
             throw new LicenseError(result.reason ?? 'invalid', REASON_TEXT[result.reason] ?? 'The license is not valid.');
         };
     }
+    /** What keeps this app from sending a device key. */
+    deviceKeyHint() {
+        if (this.deviceKey().devicePublicKey)
+            return 'Check online so the server sends the key for this computer.';
+        if (this.opts.hardware === false)
+            return 'The app turned hardware off (hardware: false), so it sends none.';
+        return loadHwid()
+            ? 'The installed @carchalabs/seal-hwid is too old to open device-bound keys with this app\'s keys (0.5 or later).'
+            : 'It needs the native module @carchalabs/seal-hwid, which is not installed or has no build for this platform.';
+    }
     /**
      * Offline activation, step 1 on a machine that cannot reach the server: the request file (JSON text)
      * the user takes to a connected device. The license server turns it into a license file at
@@ -702,7 +770,8 @@ class Seal {
     /**
      * 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.
+     * Throws `unlicensed` when there is no license to remove, and `storage_unreadable` when the saved one cannot be read
+     * (nothing is removed).
      */
     deactivateOffline() {
         return this.serial(() => this.deactivateOfflineNow());
@@ -740,7 +809,7 @@ class Seal {
      * 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,
+     * LicenseError: `unlicensed`, `storage_unreadable` (no key given and the saved one cannot be read), 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 = {}) {
@@ -759,7 +828,7 @@ class Seal {
         // 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)
+                if ((await this.loadIfReadable())?.licenseKey !== key)
                     await this.save({ licenseKey: key });
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carchalabs/seal-electron",
-  "version": "0.8.0",
+  "version": "0.9.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/",
@@ -15,10 +15,10 @@
     "test": "node --no-warnings=ExperimentalWarning --test dist/*.test.js"
   },
   "dependencies": {
-    "@carchalabs/seal-core": "0.6.0"
+    "@carchalabs/seal-core": "0.7.0"
   },
   "optionalDependencies": {
-    "@carchalabs/seal-hwid": "0.6.0"
+    "@carchalabs/seal-hwid": "0.6.1"
   },
   "engines": { "node": ">=22.13" },
   "publishConfig": { "access": "public" },