@antondziuin/talos-sdk 0.2.1 → 0.3.0

package/README.md

@@ -240,6 +240,25 @@ so an anchor-only pin still works with no server to fetch one from. The verdict
 is kept, so later starts need nothing — `validate()` re-checks the stored file
 instead of reaching for the network, and `isActivated` is true.
 
+A **portable** permanent file is issued directly by the vendor. Import it with
+`loadOfflineLicense("license.talos")` on each computer; no request or machine
+key is needed. Its signed `binding: "portable"` explicitly permits use on
+different computers. Each computer keeps its own local state; carry the licence
+file rather than copying machine-encrypted state. Portable files can be copied
+and remain usable indefinitely. `createOfflineDeactivation()` refuses them
+because they have no bound seat to return.
+
+A valid offline import replaces any existing online activation locally, so
+later `validate()` calls and restarts use the file without contacting Talos.
+Rejected imports preserve the previous stored activation. Keep state
+persistence enabled for automatic restore.
+
+For trusted users, a perpetual policy can opt into permanent offline files with
+`offline_checkout_max_days: 0`. The issued file has a signed `perpetual: true`
+and explicit null file and licence expiries. It needs no renewal or server
+connection; `graceUntil` and `licenseExpiresAt` are null. Import it using the
+same calls above. Older SDK versions reject these files and must be upgraded.
+
 `loadOfflineLicense` **throws** only for a file that is not a licence: unreadable,
 not one of ours, addressed to another product, or a signature that does not
 verify. A file that is one but cannot license this machine comes back as a
@@ -255,9 +274,9 @@ receipt changes nothing.
 Two things to know before you offer this to customers. A file **cannot be
 recalled** — revoking it in the portal frees the seat so you can issue to a
 replacement machine, but the machine holding it keeps working until the file's
-own expiry, which is why the policy's horizon is short. And hardware changes are
-not forgiven offline: the drift matcher lives on the server, so a replaced disk
-means `machine_mismatch` and a new request.
+own expiry, or indefinitely for a permanent file. Hardware changes to a
+machine-bound install are not forgiven offline: the drift matcher lives on the
+server, so a replaced disk means `machine_mismatch` and a new request.
 
 ## Heartbeats, monitoring, and cadence
 

package/dist/index.cjs

@@ -288,7 +288,7 @@ var StateStore = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.2.1";
+var SDK_VERSION = "0.3.0";
 var SDK_ID = `node/${SDK_VERSION}`;
 
 // src/diagnostics.ts
@@ -516,6 +516,9 @@ var TalosClient = class {
    * for weeks. A key revoked in the portal would never reach it.
    */
   keysetIssuedAt = 0;
+  keysetToken = null;
+  /** Invalidates online work started before a local licensing-mode change. */
+  licensingGeneration = 0;
   /** The policy's heartbeat cadence, from the last heartbeat's signed claims. */
   heartbeatInterval = null;
   checkInTimer = null;
@@ -638,12 +641,14 @@ var TalosClient = class {
    */
   async refreshKeyset() {
     if (!this.anchorKey) return;
+    const generation = this.licensingGeneration;
     const body = await this.post("/v1/client/keyset", {
       product_token: this.options.productToken
     });
+    if (generation !== this.licensingGeneration) return;
     this.adoptKeyset(body["keyset"]);
     this.keysetFromCache = false;
-    if (typeof body["keyset"] === "string") this.persist({ keyset: body["keyset"] });
+    if (this.keysetToken) this.persist({ keyset: this.keysetToken });
   }
   /**
    * Make sure a verification key exists before a response has to be verified.
@@ -694,7 +699,8 @@ var TalosClient = class {
     if (!this.anchorKey || typeof token !== "string") return;
     const claims = verifyKeyset(this.anchorKey, this.options.productToken, token);
     const iat = claims["iat"];
-    this.keysetIssuedAt = typeof iat === "number" ? iat : 0;
+    const issuedAt = typeof iat === "number" ? iat : 0;
+    if (issuedAt < this.keysetIssuedAt || issuedAt === this.keysetIssuedAt && this.keysetToken !== null && token !== this.keysetToken) return;
     const licenseKeys = [];
     const releaseKeys = [];
     for (const entry of asArray(claims["keys"])) {
@@ -706,6 +712,8 @@ var TalosClient = class {
     }
     this.keysetLicenseKeys = licenseKeys;
     this.keysetReleaseKeys = releaseKeys;
+    this.keysetIssuedAt = issuedAt;
+    this.keysetToken = token;
   }
   /** Keys to verify license tokens with: the keyset if loaded, else the direct pin. */
   licenseVerifyKeys() {
@@ -737,62 +745,71 @@ var TalosClient = class {
    * elsewhere.
    */
   async activate(licenseKey) {
-    if (this.isActivated && this.licenseKeyHash === hashLicenseKey(licenseKey)) {
-      try {
-        const state = await this.validate();
-        if (state.decision !== "deactivated") return state;
-      } catch (e) {
-        const stale = e instanceof TalosApiError && (e.statusCode === 401 || e.statusCode === 404);
-        if (!stale) throw e;
+    const generation = this.licensingGeneration;
+    try {
+      if (this.isActivated && this.licenseKeyHash === hashLicenseKey(licenseKey)) {
+        try {
+          const state = await this.validate();
+          if (state.decision !== "deactivated") return state;
+        } catch (e) {
+          const stale = e instanceof TalosApiError && (e.statusCode === 401 || e.statusCode === 404);
+          if (!stale) throw e;
+        }
+        this.forgetBinding();
       }
-      this.forgetBinding();
+      const nonce = newNonce();
+      const body = await this.post("/v1/client/activate", {
+        product_token: this.options.productToken,
+        license_key: licenseKey,
+        fingerprint: { composite: this.fingerprint, components: this.fp.components },
+        nonce,
+        hostname: this.reportedHostname(),
+        os: `${import_node_os3.default.type()} ${import_node_os3.default.release()}`,
+        arch: import_node_os3.default.arch(),
+        app_version: this.options.appVersion,
+        sdk_version: SDK_ID
+      });
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
+      this.adoptKeyset(body["keyset"]);
+      const claims = verifyToken(
+        this.licenseVerifyKeys(),
+        "activation",
+        this.options.productToken,
+        nonce,
+        body["activation_token"]
+      );
+      this.licenseKeyHash = hashLicenseKey(licenseKey);
+      this.activationSecret = body["activation_secret"];
+      this.machineId = body["machine_id"] ?? null;
+      this.binding = {
+        licenseKeyHash: this.licenseKeyHash,
+        activationSecret: this.activationSecret,
+        machineId: this.machineId ?? "",
+        fingerprint: this.fingerprint,
+        // A fresh activation invalidates any cached verdict for the previous
+        // binding; keep only the keyset, which is per product, not per machine.
+        keyset: this.keysetToken ?? this.binding?.keyset,
+        timeHighWater: this.binding?.timeHighWater,
+        // The machine's own identity survives an online activation, because it is
+        // an identity and not a verdict: an install that reaches the network once
+        // must not have to repeat the whole air-gapped ceremony with its vendor
+        // the next time it is unplugged. The clock mark survives for the same
+        // reason a mark exists at all — it only moves forward.
+        machineKey: this.binding?.machineKey,
+        machinePublicKey: this.binding?.machinePublicKey,
+        offlineSeen: this.binding?.offlineSeen
+        // The offline *file* does not: a live activation supersedes it, and
+        // keeping it would leave two answers to "what licenses this machine".
+      };
+      this.advanceClock(claims);
+      this.store?.save(this.binding);
+      return this.adopt(stateFromClaims(claims, "valid", false));
+    } catch (e) {
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
+      throw e;
     }
-    const nonce = newNonce();
-    const body = await this.post("/v1/client/activate", {
-      product_token: this.options.productToken,
-      license_key: licenseKey,
-      fingerprint: { composite: this.fingerprint, components: this.fp.components },
-      nonce,
-      hostname: this.reportedHostname(),
-      os: `${import_node_os3.default.type()} ${import_node_os3.default.release()}`,
-      arch: import_node_os3.default.arch(),
-      app_version: this.options.appVersion,
-      sdk_version: SDK_ID
-    });
-    this.adoptKeyset(body["keyset"]);
-    const claims = verifyToken(
-      this.licenseVerifyKeys(),
-      "activation",
-      this.options.productToken,
-      nonce,
-      body["activation_token"]
-    );
-    this.licenseKeyHash = hashLicenseKey(licenseKey);
-    this.activationSecret = body["activation_secret"];
-    this.machineId = body["machine_id"] ?? null;
-    this.binding = {
-      licenseKeyHash: this.licenseKeyHash,
-      activationSecret: this.activationSecret,
-      machineId: this.machineId ?? "",
-      fingerprint: this.fingerprint,
-      // A fresh activation invalidates any cached verdict for the previous
-      // binding; keep only the keyset, which is per product, not per machine.
-      keyset: typeof body["keyset"] === "string" ? body["keyset"] : this.binding?.keyset,
-      timeHighWater: this.binding?.timeHighWater,
-      // The machine's own identity survives an online activation, because it is
-      // an identity and not a verdict: an install that reaches the network once
-      // must not have to repeat the whole air-gapped ceremony with its vendor
-      // the next time it is unplugged. The clock mark survives for the same
-      // reason a mark exists at all — it only moves forward.
-      machineKey: this.binding?.machineKey,
-      machinePublicKey: this.binding?.machinePublicKey,
-      offlineSeen: this.binding?.offlineSeen
-      // The offline *file* does not: a live activation supersedes it, and
-      // keeping it would leave two answers to "what licenses this machine".
-    };
-    this.advanceClock(claims);
-    this.store?.save(this.binding);
-    return this.adopt(stateFromClaims(claims, "valid", false));
   }
   /**
    * This machine's own keypair, generated once and kept in the state file.
@@ -867,13 +884,13 @@ var TalosClient = class {
     });
   }
   /**
-   * Adopt an air-gapped licence file issued for this machine.
+   * Adopt a machine-bound or portable offline licence file.
    *
    * Everything is verified locally, because there is nothing to ask: the
    * anchor-signed keyset travels inside the file, the verdict is signed by a key
-   * that keyset lists, and the file names both halves of this machine's identity
-   * — its fingerprint and the public key it generated. The verdict is then kept,
-   * so later starts are licensed with no further ceremony.
+   * that keyset lists. Machine-bound files name this machine's fingerprint and
+   * public key; explicitly portable files need no machine request. The verdict
+   * is kept, so later starts are licensed with no further ceremony.
    *
    * **Throws** only for a file that is not a licence: unreadable, not one of
    * ours, addressed to another product, or a broken signature. A file that *is*
@@ -896,8 +913,27 @@ var TalosClient = class {
     if (doc["kind"] !== LICENSE_FILE_KIND || typeof doc["token"] !== "string") {
       throw new TalosError("not a Talos offline licence file");
     }
-    if (typeof doc["keyset"] === "string") this.adoptKeyset(doc["keyset"]);
-    return this.adoptOfflineToken(doc["token"], doc["keyset"]);
+    const previous = {
+      license: this.keysetLicenseKeys,
+      release: this.keysetReleaseKeys,
+      iat: this.keysetIssuedAt,
+      token: this.keysetToken
+    };
+    const restore = () => {
+      this.keysetLicenseKeys = previous.license;
+      this.keysetReleaseKeys = previous.release;
+      this.keysetIssuedAt = previous.iat;
+      this.keysetToken = previous.token;
+    };
+    try {
+      if (typeof doc["keyset"] === "string") this.adoptKeyset(doc["keyset"]);
+      const state = this.adoptOfflineToken(doc["token"], this.keysetToken);
+      if (!state.isValid) restore();
+      return state;
+    } catch (e) {
+      restore();
+      throw e;
+    }
   }
   /**
    * Hand this machine's air-gapped seat back.
@@ -919,9 +955,7 @@ var TalosClient = class {
    */
   createOfflineDeactivation() {
     const token = this.binding?.offlineToken;
-    const key = this.binding?.machineKey;
-    const pub = this.binding?.machinePublicKey;
-    if (!token || !key || !pub) {
+    if (!token) {
       throw new TalosError("no offline licence to hand back");
     }
     let claims;
@@ -935,6 +969,12 @@ var TalosClient = class {
     } catch {
       throw new TalosError("the stored offline licence no longer verifies");
     }
+    if (claims["binding"] === "portable") {
+      throw new TalosError("portable offline licences have no bound seat to return");
+    }
+    const key = this.binding?.machineKey;
+    const pub = this.binding?.machinePublicKey;
+    if (!key || !pub) throw new TalosError("no offline licence to hand back");
     this.binding = { ...this.bindingBase(), offlineToken: void 0 };
     this.current = null;
     this.store?.save(this.binding);
@@ -959,38 +999,58 @@ var TalosClient = class {
       token
     );
     const mismatch = () => this.adopt(new LicenseState("machine_mismatch", {}, null, true, null, null));
-    if (typeof claims["mpk"] !== "string" || claims["mpk"] !== this.binding?.machinePublicKey) {
+    const lic = claims["lic"] ?? {};
+    const features = lic["features"] ?? {};
+    const licExp = num(lic["lic_exp"]);
+    const exp = num(claims["exp"]);
+    const perpetual = claims["perpetual"] === true && claims["exp"] === null && lic["lic_exp"] === null;
+    const portable = claims["binding"] === "portable";
+    if (portable) {
+      const present = (key) => Object.hasOwn(claims, key);
+      const named = (key) => typeof claims[key] === "string" && claims[key].trim().length > 0;
+      if (!perpetual || claims["decision"] !== "valid" || present("fph") || present("mpk") || present("mid") || !named("fid") || !named("sub")) return mismatch();
+    } else if (claims["binding"] !== void 0 && claims["binding"] !== "machine") {
+      return mismatch();
+    }
+    if (!portable && (typeof claims["mpk"] !== "string" || claims["mpk"] !== this.binding?.machinePublicKey)) {
       return mismatch();
     }
-    if (claims["fph"] !== this.fingerprint) return mismatch();
+    if (!portable && claims["fph"] !== this.fingerprint) return mismatch();
     const now = nowSeconds();
     const mark = Math.max(this.binding?.timeHighWater ?? 0, this.binding?.offlineSeen ?? 0);
     if (mark > 0 && now + CLOCK_SKEW_SECONDS2 < mark) {
       return this.adopt(new LicenseState("clock_tampered", {}, null, true, null, null));
     }
-    const lic = claims["lic"] ?? {};
-    const features = lic["features"] ?? {};
-    const licExp = num(lic["lic_exp"]);
-    const exp = num(claims["exp"]);
-    this.machineId = typeof claims["mid"] === "string" ? claims["mid"] : this.machineId;
+    if (!perpetual && (exp === null || now > exp)) {
+      return this.adopt(
+        new LicenseState("offline_file_expired", features, licExp, true, null, exp)
+      );
+    }
+    if (licExp !== null && now > licExp) {
+      return this.adopt(new LicenseState("expired", features, licExp, true, null, exp));
+    }
+    this.licensingGeneration += 1;
+    this.licenseKeyHash = null;
+    this.activationSecret = null;
+    this.heartbeatInterval = null;
+    this.leaseGeneration += 1;
+    this.stopRenew();
+    this.lease = null;
+    this.machineId = !portable && typeof claims["mid"] === "string" ? claims["mid"] : null;
     const base = this.bindingBase();
     this.binding = {
       ...base,
-      machineId: this.machineId ?? base.machineId,
+      licenseKeyHash: "",
+      activationSecret: "",
+      validation: void 0,
+      machineId: this.machineId ?? "",
+      fingerprint: this.fingerprint,
       offlineToken: token,
       offlineSeen: Math.max(base.offlineSeen ?? 0, now),
       ...typeof keyset === "string" ? { keyset } : {}
     };
     this.advanceClock(claims);
     this.store?.save(this.binding);
-    if (exp === null || now > exp) {
-      return this.adopt(
-        new LicenseState("offline_file_expired", features, licExp, true, null, exp)
-      );
-    }
-    if (licExp !== null && now > licExp) {
-      return this.adopt(new LicenseState("expired", features, licExp, true, null, exp));
-    }
     return this.adopt(new LicenseState("valid", features, licExp, true, null, exp));
   }
   /**
@@ -1103,6 +1163,7 @@ var TalosClient = class {
   }
   /** Drop the machine binding, in memory and on disk. */
   forgetBinding() {
+    this.licensingGeneration += 1;
     this.licenseKeyHash = null;
     this.activationSecret = null;
     this.machineId = null;
@@ -1136,8 +1197,11 @@ var TalosClient = class {
       return this.adoptOfflineToken(this.binding.offlineToken);
     }
     this.requireActivated();
+    const generation = this.licensingGeneration;
     try {
       await this.ensureKeyset();
+      const switchedBeforeRequest = this.offlineSince(generation);
+      if (switchedBeforeRequest) return switchedBeforeRequest;
       const nonce = newNonce();
       const body = await this.post("/v1/client/validate", {
         product_token: this.options.productToken,
@@ -1151,6 +1215,8 @@ var TalosClient = class {
         app_version: this.options.appVersion,
         sdk_version: SDK_ID
       });
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
       const token = body["validation_token"];
       const claims = verifyToken(
         this.licenseVerifyKeys(),
@@ -1164,6 +1230,8 @@ var TalosClient = class {
       this.persist({ validation: token, timeHighWater: this.binding?.timeHighWater });
       return this.adopt(stateFromClaims(claims, decision, false));
     } catch (e) {
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
       if (e instanceof TalosApiError) throw e;
       const offline = this.offlineDecision();
       if (!offline) throw e;
@@ -1236,12 +1304,13 @@ var TalosClient = class {
   }
   async deactivate() {
     this.requireActivated();
+    const generation = this.licensingGeneration;
     await this.post("/v1/client/deactivate", {
       product_token: this.options.productToken,
       fingerprint: { composite: this.fingerprint, components: this.fp.components },
       activation_secret: this.activationSecret
     });
-    this.forgetBinding();
+    if (generation === this.licensingGeneration) this.forgetBinding();
   }
   /**
    * Send a heartbeat: refreshes this machine's last-seen state, feeds the
@@ -1265,46 +1334,59 @@ var TalosClient = class {
   }
   async heartbeat() {
     this.requireActivated();
-    await this.ensureKeyset();
-    const nonce = newNonce();
-    const body = await this.post("/v1/client/heartbeat", {
-      product_token: this.options.productToken,
-      fingerprint: { composite: this.fingerprint, components: this.fp.components },
-      activation_secret: this.activationSecret,
-      nonce,
-      app_version: this.options.appVersion,
-      os: `${import_node_os3.default.type()} ${import_node_os3.default.release()}`,
-      arch: import_node_os3.default.arch(),
-      sdk_version: SDK_ID,
-      // Naming the channel is what asks the server for the update hint, and it
-      // costs two queries there — so it is asked for only when somebody is
-      // listening for the answer.
-      update_channel: this.listeners.get("updateAvailable")?.size ? this.updateChannel() : void 0
-    });
-    const claims = verifyToken(
-      this.licenseVerifyKeys(),
-      "heartbeat",
-      this.options.productToken,
-      nonce,
-      body["heartbeat_token"]
-    );
-    const decision = typeof claims["decision"] === "string" ? claims["decision"] : "invalid";
-    const interval = num(claims["heartbeat_interval_s"]);
-    if (interval !== null && interval > 0) this.heartbeatInterval = interval;
-    this.advanceClock(claims);
-    this.persist({ timeHighWater: this.binding?.timeHighWater });
-    const state = this.adopt(
-      new LicenseState(
-        decision,
-        this.current?.features ?? {},
-        this.current?.licenseExpiresAt ?? null,
-        false,
-        this.current?.revalidateAfter ?? null,
-        this.current?.graceUntil ?? null
-      )
-    );
-    await this.announceUpdate(claims);
-    return state;
+    const generation = this.licensingGeneration;
+    try {
+      await this.ensureKeyset();
+      const switchedBeforeRequest = this.offlineSince(generation);
+      if (switchedBeforeRequest) return switchedBeforeRequest;
+      const nonce = newNonce();
+      const body = await this.post("/v1/client/heartbeat", {
+        product_token: this.options.productToken,
+        fingerprint: { composite: this.fingerprint, components: this.fp.components },
+        activation_secret: this.activationSecret,
+        nonce,
+        app_version: this.options.appVersion,
+        os: `${import_node_os3.default.type()} ${import_node_os3.default.release()}`,
+        arch: import_node_os3.default.arch(),
+        sdk_version: SDK_ID,
+        // Naming the channel is what asks the server for the update hint, and it
+        // costs two queries there — so it is asked for only when somebody is
+        // listening for the answer.
+        update_channel: this.listeners.get("updateAvailable")?.size ? this.updateChannel() : void 0
+      });
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
+      const claims = verifyToken(
+        this.licenseVerifyKeys(),
+        "heartbeat",
+        this.options.productToken,
+        nonce,
+        body["heartbeat_token"]
+      );
+      const decision = typeof claims["decision"] === "string" ? claims["decision"] : "invalid";
+      const interval = num(claims["heartbeat_interval_s"]);
+      if (interval !== null && interval > 0) this.heartbeatInterval = interval;
+      this.advanceClock(claims);
+      this.persist({ timeHighWater: this.binding?.timeHighWater });
+      const state = this.adopt(
+        new LicenseState(
+          decision,
+          this.current?.features ?? {},
+          this.current?.licenseExpiresAt ?? null,
+          false,
+          this.current?.revalidateAfter ?? null,
+          this.current?.graceUntil ?? null
+        )
+      );
+      await this.announceUpdate(claims);
+      const switchedAfterUpdate = this.offlineSince(generation);
+      if (switchedAfterUpdate) return switchedAfterUpdate;
+      return state;
+    } catch (e) {
+      const switched = this.offlineSince(generation);
+      if (switched) return switched;
+      throw e;
+    }
   }
   /** The channel this install follows; `stable` unless set. */
   updateChannel() {
@@ -1689,6 +1771,13 @@ var TalosClient = class {
       throw new TalosError("not activated: call activate() first");
     }
   }
+  /** Keep a newly imported offline licence authoritative over older requests. */
+  offlineSince(generation) {
+    if (generation === this.licensingGeneration || this.activationSecret || !this.binding?.offlineToken) {
+      return null;
+    }
+    return this.adoptOfflineToken(this.binding.offlineToken);
+  }
   post(path, body) {
     return this.request("POST", path, body);
   }