@antondziuin/talos-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1512 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LicenseState: () => LicenseState,
+  StateStore: () => StateStore,
+  TalosApiError: () => TalosApiError,
+  TalosClient: () => TalosClient,
+  TalosError: () => TalosError,
+  TalosSignatureError: () => TalosSignatureError,
+  collectFingerprint: () => collectFingerprint,
+  defaultStatePath: () => defaultStatePath,
+  hashLicenseKey: () => hashLicenseKey,
+  publicKeyFromBase64: () => publicKeyFromBase64,
+  verifyAppliedUpdate: () => verifyAppliedUpdate,
+  verifyKeyset: () => verifyKeyset,
+  verifyManifest: () => verifyManifest,
+  verifyToken: () => verifyToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_crypto5 = require("crypto");
+var import_node_fs3 = require("fs");
+var import_promises = require("fs/promises");
+var import_node_os3 = __toESM(require("os"), 1);
+var import_node_crypto6 = require("crypto");
+
+// src/errors.ts
+var TalosError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TalosError";
+  }
+};
+var TalosSignatureError = class extends TalosError {
+  constructor(message) {
+    super(message);
+    this.name = "TalosSignatureError";
+  }
+};
+var TalosApiError = class extends TalosError {
+  statusCode;
+  errorCode;
+  constructor(statusCode, errorCode) {
+    super(`talos api error ${statusCode}${errorCode ? `: ${errorCode}` : ""}`);
+    this.name = "TalosApiError";
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+  }
+};
+
+// src/fingerprint.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_os = __toESM(require("os"), 1);
+function collectFingerprint(productToken, extra) {
+  const key = (0, import_node_crypto.createHash)("sha256").update("talos-fp|" + productToken).digest();
+  const raw = {
+    machine_guid: machineGuid(),
+    smbios_uuid: readFile("/sys/class/dmi/id/product_uuid"),
+    disk_serial: readFile("/sys/class/dmi/id/board_serial"),
+    mac_set: macSet(),
+    cpu: cpu(),
+    mem_bucket: memBucket(),
+    os_install: osInstall(),
+    hostname: safe(() => import_node_os.default.hostname()),
+    ...extra
+  };
+  const components = {};
+  for (const id of Object.keys(raw).sort()) {
+    const value = raw[id];
+    if (value === void 0 || value === null || value.trim() === "") continue;
+    components[id] = (0, import_node_crypto.createHmac)("sha256", key).update(id + "=" + value.trim()).digest("hex").slice(0, 32);
+  }
+  const canonical = Object.entries(components).map(([k, v]) => `${k}=${v}`).join("\n");
+  return {
+    composite: "fp2:" + (0, import_node_crypto.createHash)("sha256").update(canonical).digest("hex"),
+    components
+  };
+}
+function machineGuid() {
+  return readFile("/etc/machine-id") ?? readFile("/var/lib/dbus/machine-id");
+}
+function macSet() {
+  return safe(() => {
+    const macs = Object.values(import_node_os.default.networkInterfaces()).flat().filter((i) => Boolean(i) && !i.internal).map((i) => i.mac).filter((m) => m && m !== "00:00:00:00:00:00").filter((m, i, all) => all.indexOf(m) === i).sort();
+    return macs.length === 0 ? void 0 : macs.join(",");
+  });
+}
+function cpu() {
+  return safe(() => {
+    const cpus = import_node_os.default.cpus();
+    if (!cpus || cpus.length === 0) return void 0;
+    return `${cpus[0].model}|${cpus.length}`;
+  });
+}
+function memBucket() {
+  return safe(() => {
+    const gib = Math.floor(import_node_os.default.totalmem() / 1024 ** 3);
+    if (gib < 1) return void 0;
+    let bucket = 1;
+    while (bucket * 2 <= gib) bucket *= 2;
+    return String(bucket);
+  });
+}
+function osInstall() {
+  const path = import_node_os.default.platform() === "win32" ? process.env.SystemRoot ?? "C:\\Windows" : "/etc";
+  return safe(() => {
+    const birth = (0, import_node_fs.statSync)(path).birthtimeMs;
+    return birth > 0 ? String(Math.floor(birth / 1e3)) : void 0;
+  });
+}
+function readFile(path) {
+  return safe(() => {
+    const text = (0, import_node_fs.readFileSync)(path, "utf8").trim();
+    return text.length === 0 ? void 0 : text;
+  });
+}
+function safe(f) {
+  try {
+    return f();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/state.ts
+var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_path = require("path");
+var import_node_os2 = __toESM(require("os"), 1);
+var MAGIC = Buffer.from("TLS1");
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var SALT = Buffer.from("talos-state-v1");
+function defaultStatePath(productToken) {
+  return statePathFor(productToken, import_node_os2.default.platform(), import_node_os2.default.homedir(), process.env);
+}
+function statePathFor(productToken, platform, home, env) {
+  const slot = (0, import_node_crypto2.createHash)("sha256").update(productToken).digest("hex").slice(0, 16);
+  switch (platform) {
+    case "win32":
+      return (0, import_node_path.join)(env["LOCALAPPDATA"] || (0, import_node_path.join)(home, "AppData", "Local"), "Talos", slot, "state.bin");
+    case "darwin":
+      return (0, import_node_path.join)(home, "Library", "Application Support", "Talos", slot, "state.bin");
+    default:
+      return (0, import_node_path.join)(env["XDG_DATA_HOME"] || (0, import_node_path.join)(home, ".local", "share"), "talos", slot, "state.bin");
+  }
+}
+function stateKeyMaterial(fp) {
+  return fp.components["machine_guid"] ?? fp.components["smbios_uuid"] ?? fp.components["os_install"] ?? "talos-unbound";
+}
+function hashLicenseKey(key) {
+  return (0, import_node_crypto2.createHash)("sha256").update(key, "utf8").digest("hex");
+}
+var StateStore = class {
+  constructor(path, productToken, keyMaterial) {
+    this.path = path;
+    this.productToken = productToken;
+    this.key = Buffer.from(
+      (0, import_node_crypto2.hkdfSync)("sha256", Buffer.from(keyMaterial), SALT, Buffer.from(productToken), 32)
+    );
+  }
+  path;
+  productToken;
+  key;
+  /**
+   * Load the binding, or null if there is none.
+   *
+   * Never throws. A state file that is missing, truncated, from another
+   * product, written by a future version, or simply corrupt must degrade to
+   * "not activated yet" — the app then activates again. Throwing here would
+   * turn a damaged cache into a launch failure.
+   */
+  load() {
+    let raw;
+    try {
+      raw = (0, import_node_fs2.readFileSync)(this.path);
+    } catch {
+      return null;
+    }
+    try {
+      if (raw.length < MAGIC.length + IV_LEN + TAG_LEN) return null;
+      if (!raw.subarray(0, MAGIC.length).equals(MAGIC)) return null;
+      const iv = raw.subarray(MAGIC.length, MAGIC.length + IV_LEN);
+      const tag = raw.subarray(MAGIC.length + IV_LEN, MAGIC.length + IV_LEN + TAG_LEN);
+      const body = raw.subarray(MAGIC.length + IV_LEN + TAG_LEN);
+      const d = (0, import_node_crypto2.createDecipheriv)("aes-256-gcm", this.key, iv);
+      d.setAAD(Buffer.from(this.productToken));
+      d.setAuthTag(tag);
+      const plain = Buffer.concat([d.update(body), d.final()]).toString("utf8");
+      const o = JSON.parse(plain);
+      if (o["v"] !== 1) return null;
+      const legacyKey = typeof o["licenseKey"] === "string" ? o["licenseKey"] : "";
+      const b = {
+        licenseKeyHash: typeof o["licenseKeyHash"] === "string" && o["licenseKeyHash"] ? o["licenseKeyHash"] : legacyKey ? hashLicenseKey(legacyKey) : "",
+        activationSecret: String(o["activationSecret"] ?? ""),
+        machineId: String(o["machineId"] ?? ""),
+        fingerprint: String(o["fingerprint"] ?? "")
+      };
+      if (typeof o["keyset"] === "string") b.keyset = o["keyset"];
+      if (typeof o["validation"] === "string") b.validation = o["validation"];
+      if (typeof o["timeHighWater"] === "number") b.timeHighWater = o["timeHighWater"];
+      if (typeof o["releaseSeqHighWater"] === "number") {
+        b.releaseSeqHighWater = o["releaseSeqHighWater"];
+      }
+      const pending = o["pendingRelease"];
+      if (pending && typeof pending["version"] === "string" && typeof pending["releaseSeq"] === "number") {
+        b.pendingRelease = { version: pending["version"], releaseSeq: pending["releaseSeq"] };
+      }
+      return b.activationSecret ? b : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Persist the binding. Best-effort by design: a read-only or full disk costs
+   * the user a re-activation next launch, and must not fail the activation
+   * that just succeeded.
+   */
+  save(b) {
+    try {
+      const plain = Buffer.from(JSON.stringify({ v: 1, ...b }), "utf8");
+      const iv = (0, import_node_crypto3.randomBytes)(IV_LEN);
+      const c = (0, import_node_crypto2.createCipheriv)("aes-256-gcm", this.key, iv);
+      c.setAAD(Buffer.from(this.productToken));
+      const body = Buffer.concat([c.update(plain), c.final()]);
+      const out = Buffer.concat([MAGIC, iv, c.getAuthTag(), body]);
+      (0, import_node_fs2.mkdirSync)((0, import_node_path.dirname)(this.path), { recursive: true, mode: 448 });
+      const tmp = `${this.path}.tmp`;
+      (0, import_node_fs2.writeFileSync)(tmp, out, { mode: 384 });
+      try {
+        (0, import_node_fs2.chmodSync)(tmp, 384);
+      } catch {
+      }
+      (0, import_node_fs2.renameSync)(tmp, this.path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Forget the binding (deactivation). */
+  clear() {
+    try {
+      (0, import_node_fs2.rmSync)(this.path, { force: true });
+    } catch {
+    }
+  }
+};
+
+// src/version.ts
+var SDK_VERSION = "0.1.0";
+var SDK_ID = `node/${SDK_VERSION}`;
+
+// src/talos-compact.ts
+var import_node_crypto4 = require("crypto");
+var SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+var CLOCK_SKEW_SECONDS = 60;
+function publicKeyFromBase64(b64) {
+  const raw = Buffer.from(b64, "base64");
+  if (raw.length !== 32) {
+    throw new Error("public key must decode to 32 bytes");
+  }
+  const der = Buffer.concat([SPKI_PREFIX, raw]);
+  return (0, import_node_crypto4.createPublicKey)({ key: der, format: "der", type: "spki" });
+}
+function b64urlDecode(s) {
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+function b64urlEncode(buf) {
+  return buf.toString("base64").replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function parseAndVerify(keys, token, expectedTyp) {
+  const list = Array.isArray(keys) ? keys : [keys];
+  const parts = token.split(".");
+  if (parts.length !== 5) throw new TalosSignatureError("malformed token");
+  if (parts[0] !== "talos") throw new TalosSignatureError("unexpected scheme");
+  if (parts[1] !== "1") throw new TalosSignatureError("unsupported wire version");
+  if (parts[2] !== expectedTyp) throw new TalosSignatureError("token type mismatch");
+  if (list.length === 0) throw new TalosSignatureError("no verification key");
+  const lastDot = token.lastIndexOf(".");
+  const prefix = Buffer.from(token.slice(0, lastDot), "ascii");
+  const sig = b64urlDecode(parts[4]);
+  const ok = list.some((k) => (0, import_node_crypto4.verify)(null, prefix, k, sig));
+  if (!ok) throw new TalosSignatureError("signature verification failed");
+  return JSON.parse(b64urlDecode(parts[3]).toString("utf8"));
+}
+function verifyToken(keys, expectedTyp, expectedAud, expectedNonce, token) {
+  const claims = parseAndVerify(keys, token, expectedTyp);
+  if (claims["aud"] !== expectedAud) throw new TalosSignatureError("audience mismatch");
+  if (claims["non"] !== expectedNonce) {
+    throw new TalosSignatureError("nonce mismatch (possible replay)");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const nbf = claims["nbf"];
+  if (typeof nbf !== "number") throw new TalosSignatureError("token has no nbf");
+  if (now + CLOCK_SKEW_SECONDS < nbf) {
+    throw new TalosSignatureError("token not yet valid");
+  }
+  const exp = claims["exp"];
+  if (typeof exp !== "number") throw new TalosSignatureError("token has no exp");
+  if (now - CLOCK_SKEW_SECONDS > exp) {
+    throw new TalosSignatureError("token expired");
+  }
+  return claims;
+}
+function verifyCachedToken(keys, expectedTyp, expectedAud, token) {
+  const claims = parseAndVerify(keys, token, expectedTyp);
+  if (claims["aud"] !== expectedAud) throw new TalosSignatureError("audience mismatch");
+  const nbf = claims["nbf"];
+  if (typeof nbf === "number" && Math.floor(Date.now() / 1e3) + CLOCK_SKEW_SECONDS < nbf) {
+    throw new TalosSignatureError("cached token not yet valid");
+  }
+  return claims;
+}
+function verifyManifest(releaseKeys, expectedAud, token) {
+  const claims = parseAndVerify(releaseKeys, token, "manifest");
+  if (claims["aud"] !== expectedAud) throw new TalosSignatureError("audience mismatch");
+  const notBefore = claims["not_before"];
+  if (typeof notBefore === "number") {
+    const now = Math.floor(Date.now() / 1e3);
+    if (now + CLOCK_SKEW_SECONDS < notBefore) {
+      throw new TalosSignatureError("manifest not yet released");
+    }
+  }
+  return claims;
+}
+function verifyKeyset(anchorKey, expectedAud, token) {
+  const claims = parseAndVerify(anchorKey, token, "keyset");
+  if (claims["aud"] !== expectedAud) throw new TalosSignatureError("audience mismatch");
+  return claims;
+}
+
+// src/client.ts
+var CLOCK_SKEW_SECONDS2 = 60;
+var DEFAULT_HEARTBEAT_SECONDS = 600;
+var DEFAULT_HTTP_TIMEOUT_MS = 1e4;
+var LicenseState = class {
+  constructor(decision, features, licenseExpiresAt, isOffline = false, revalidateAfter = null, graceUntil = null) {
+    this.decision = decision;
+    this.features = features;
+    this.licenseExpiresAt = licenseExpiresAt;
+    this.isOffline = isOffline;
+    this.revalidateAfter = revalidateAfter;
+    this.graceUntil = graceUntil;
+  }
+  decision;
+  features;
+  licenseExpiresAt;
+  isOffline;
+  revalidateAfter;
+  graceUntil;
+  get isValid() {
+    return this.decision === "valid";
+  }
+  isFeatureEnabled(name) {
+    const v = this.features[name];
+    if (typeof v === "boolean") return v;
+    if (typeof v === "number") return v !== 0;
+    if (typeof v === "string") return v.length > 0;
+    return false;
+  }
+  getEntitlement(name) {
+    return this.features[name];
+  }
+};
+var KEYSET_MAX_AGE_SECONDS = 24 * 60 * 60;
+var TalosClient = class {
+  options;
+  anchorKey;
+  publicKey;
+  releaseKey;
+  fingerprint;
+  fp;
+  doFetch;
+  // Learned from the anchor-signed keyset; take precedence over the direct pins.
+  keysetLicenseKeys = [];
+  keysetReleaseKeys = [];
+  /**
+   * SHA-256 of the key this machine activated with, or null.
+   *
+   * The key itself is deliberately not held: after activation the server
+   * resolves the licence from the activation secret, so keeping the key would
+   * mean a plaintext credential in memory and on disk for the sake of one
+   * string comparison in `activate`.
+   */
+  licenseKeyHash = null;
+  activationSecret = null;
+  machineId = null;
+  store;
+  /** Everything persisted for this product; written back as one file. */
+  binding = null;
+  /**
+   * True while the adopted keyset came off disk. One refresh per process
+   * upgrades it, so a rotation is picked up, but a client that cannot reach the
+   * server keeps verifying with what it already trusts.
+   */
+  keysetFromCache = false;
+  /**
+   * The `iat` of the adopted keyset, in unix seconds, or 0 if unknown.
+   *
+   * Kept so a keyset can go stale. Without it the refresh happens once per
+   * process, which is fine for a desktop app that restarts and useless for the
+   * process this SDK is most often *in* — a server or an Electron main that runs
+   * for weeks. A key revoked in the portal would never reach it.
+   */
+  keysetIssuedAt = 0;
+  /** The policy's heartbeat cadence, from the last heartbeat's signed claims. */
+  heartbeatInterval = null;
+  checkInTimer = null;
+  /** Bumped on stop so an in-flight tick cannot re-arm a cancelled loop. */
+  checkInGeneration = 0;
+  lease = null;
+  renewTimer = null;
+  /** Bumped on release so an in-flight renewal cannot resurrect the seat. */
+  leaseGeneration = 0;
+  /** Default instance id for floating leases: one per client object. */
+  instanceId = b64urlEncode((0, import_node_crypto5.randomBytes)(9));
+  current = null;
+  listeners = /* @__PURE__ */ new Map();
+  /** The newest release this client has already announced. */
+  announcedReleaseSeq = 0;
+  constructor(options) {
+    if (!options.productToken) throw new TalosError("productToken required");
+    if (!options.serverUrl) throw new TalosError("serverUrl required");
+    if (!options.anchorPublicKey && !options.publicKey) {
+      throw new TalosError("anchorPublicKey or publicKey required");
+    }
+    this.options = options;
+    this.anchorKey = options.anchorPublicKey ? publicKeyFromBase64(options.anchorPublicKey) : null;
+    this.publicKey = options.publicKey ? publicKeyFromBase64(options.publicKey) : null;
+    this.releaseKey = options.releasePublicKey ? publicKeyFromBase64(options.releasePublicKey) : this.publicKey;
+    this.fp = collectFingerprint(options.productToken, options.fingerprintComponents);
+    this.fingerprint = this.fp.composite;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    if (!this.doFetch) throw new TalosError("no fetch available (need Node 18+ or options.fetch)");
+    this.store = options.persistState === false ? null : new StateStore(
+      options.statePath ?? defaultStatePath(options.productToken),
+      options.productToken,
+      stateKeyMaterial(this.fp)
+    );
+    const stored = this.store?.load() ?? null;
+    if (stored) {
+      this.binding = stored;
+      this.licenseKeyHash = stored.licenseKeyHash;
+      this.activationSecret = stored.activationSecret;
+      this.machineId = stored.machineId;
+      if (stored.keyset) {
+        try {
+          this.adoptKeyset(stored.keyset);
+          this.keysetFromCache = this.keysetLicenseKeys.length > 0;
+        } catch {
+        }
+      }
+      this.promoteDownloadedRelease();
+    }
+  }
+  /**
+   * A release that was downloaded and is now the version running: promote its
+   * `release_seq` to the anti-downgrade mark.
+   *
+   * This is the whole of "the SDK knows what is installed". The SDK downloads
+   * and verifies bytes; the host installs them, its own way, usually across a
+   * restart — so installation is not an event the SDK can observe. What it can
+   * observe is the result, because `appVersion` is the host saying which
+   * version it is. When that equals the version whose bytes were fetched, the
+   * download became an install.
+   *
+   * Only forward, and that is the point: yanking a release or lowering its
+   * rollout stops it being *offered*, and must not walk an install that already
+   * applied it back onto an older build.
+   */
+  promoteDownloadedRelease() {
+    const pending = this.binding?.pendingRelease;
+    if (!pending || pending.version !== this.options.appVersion) return;
+    const mark = Math.max(this.binding?.releaseSeqHighWater ?? 0, pending.releaseSeq);
+    this.persist({ releaseSeqHighWater: mark, pendingRelease: void 0 });
+  }
+  /**
+   * The `release_seq` no update may go at or below.
+   *
+   * The host's explicit value wins when it gives one — it knows things the SDK
+   * cannot, such as a build installed by a package manager — and the persisted
+   * mark is the default that makes anti-downgrade work for the hosts that give
+   * nothing, which is every example and most applications.
+   */
+  releaseFloor(explicit) {
+    return explicit ?? this.binding?.releaseSeqHighWater;
+  }
+  /**
+   * Whether this machine already holds an activation — restored from disk on
+   * construction, so this is the startup question: prompt for a licence key, or
+   * go straight to {@link validate}?
+   */
+  get isActivated() {
+    return this.activationSecret !== null;
+  }
+  /** The server's id for this machine, once activated. */
+  get currentMachineId() {
+    return this.machineId;
+  }
+  isFeatureEnabled(name) {
+    return this.current?.isFeatureEnabled(name) ?? false;
+  }
+  /**
+   * Fetch and verify the product's keyset (signed by the pinned anchor) and
+   * adopt its current license/release keys. Called automatically during
+   * {@link activate}; call it again after a server-side key rotation to keep
+   * verifying without any config change. No-op if no `anchorPublicKey` is pinned.
+   */
+  async refreshKeyset() {
+    if (!this.anchorKey) return;
+    const body = await this.post("/v1/client/keyset", {
+      product_token: this.options.productToken
+    });
+    this.adoptKeyset(body["keyset"]);
+    this.keysetFromCache = false;
+    if (typeof body["keyset"] === "string") this.persist({ keyset: body["keyset"] });
+  }
+  /**
+   * Make sure a verification key exists before a response has to be verified.
+   *
+   * A restored binding goes straight to `validate`, skipping `activate` — which
+   * is the only place the keyset used to be adopted. An anchor-only client (the
+   * recommended pinning, and the one that survives key rotation) therefore had
+   * nothing to verify with on the app's *second* launch, and every call failed
+   * with "keyset unavailable". Only persistence made that reachable: before it,
+   * `activate` always ran first.
+   *
+   * The keyset is also cached on disk, so the *first* call of a launch with no
+   * network can still verify a cached decision. A cached one is refreshed once
+   * per process so a rotation is picked up, but a client that cannot reach the
+   * server keeps verifying with what it already trusts.
+   */
+  async ensureKeyset() {
+    if (!this.anchorKey) return;
+    if (this.keysetLicenseKeys.length > 0 && !this.keysetFromCache && !this.keysetIsStale()) {
+      return;
+    }
+    try {
+      await this.refreshKeyset();
+    } catch (e) {
+      if (this.keysetLicenseKeys.length === 0) throw e;
+    }
+  }
+  /**
+   * Whether the adopted keyset is old enough to be worth re-fetching.
+   *
+   * This is what makes revoking a compromised signing key mean anything to an
+   * install: a revoked key is omitted from the keyset, so a client only stops
+   * trusting it once it fetches a newer one. Refreshing only on the first call
+   * of a process bounds that by "next restart", which for a long-running host is
+   * not a bound at all.
+   *
+   * A day, not an hour: the endpoint is public and unauthenticated, and every
+   * install on earth hitting it hourly is a self-inflicted load pattern for a
+   * document that changes about once a year. The honest description of the
+   * guarantee is in `docs/SECURITY.md` — revocation is bounded, not instant.
+   */
+  keysetIsStale() {
+    if (!this.keysetIssuedAt) return true;
+    return Date.now() / 1e3 - this.keysetIssuedAt > KEYSET_MAX_AGE_SECONDS;
+  }
+  /** Verify a keyset token against the anchor and adopt its keys. */
+  adoptKeyset(token) {
+    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 licenseKeys = [];
+    const releaseKeys = [];
+    for (const entry of asArray(claims["keys"])) {
+      const o = entry;
+      if (typeof o["pk"] !== "string") continue;
+      const key = publicKeyFromBase64(o["pk"]);
+      if (o["purpose"] === "license") licenseKeys.push(key);
+      else if (o["purpose"] === "release") releaseKeys.push(key);
+    }
+    this.keysetLicenseKeys = licenseKeys;
+    this.keysetReleaseKeys = releaseKeys;
+  }
+  /** Keys to verify license tokens with: the keyset if loaded, else the direct pin. */
+  licenseVerifyKeys() {
+    if (this.keysetLicenseKeys.length) return this.keysetLicenseKeys;
+    if (this.publicKey) return [this.publicKey];
+    throw new TalosSignatureError("no license verification key (keyset unavailable)");
+  }
+  /** Keys to verify manifests with: the keyset if loaded, else the direct pin. */
+  releaseVerifyKeys() {
+    if (this.keysetReleaseKeys.length) return this.keysetReleaseKeys;
+    if (this.releaseKey) return [this.releaseKey];
+    throw new TalosSignatureError("no release verification key (keyset unavailable)");
+  }
+  /**
+   * Ensure this machine is activated on `licenseKey`, and return the verified
+   * state. Safe to call on every start.
+   *
+   * When a binding for the same key is already held, this **re-validates**
+   * instead of re-activating. Same one round trip, three different outcomes:
+   * the activation secret is not rotated (so a second copy of the app on the
+   * same machine does not knock the first one out), no seat accounting is
+   * touched, and — because `activate` is the only client route refused for a
+   * suspended tenant — the developer's own paying users keep working while
+   * their vendor's account is suspended, which is what "graduated suspension"
+   * was supposed to mean.
+   *
+   * It falls back to a real activation when the stored binding is no longer
+   * usable: the seat was released from the portal, or the secret was rotated
+   * 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;
+      }
+      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
+    });
+    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
+    };
+    this.advanceClock(claims);
+    this.store?.save(this.binding);
+    return this.adopt(stateFromClaims(claims, "valid", false));
+  }
+  /**
+   * The heartbeat cadence the server's policy asks for, in seconds, taken from
+   * the last heartbeat's **signed** claims — so it cannot be lengthened in
+   * transit by anyone wanting a fleet to check in less often.
+   *
+   * `null` until the first heartbeat of this process.
+   */
+  get heartbeatIntervalSeconds() {
+    return this.heartbeatInterval;
+  }
+  /**
+   * Subscribe to a licence transition. Returns a function that unsubscribes.
+   *
+   * ```ts
+   * const off = talos.on("gracePeriodStarted", (s) => showOfflineBanner(s.graceUntil));
+   * ```
+   *
+   * Fires from every path that adopts a verdict — `activate`, `validate`,
+   * `heartbeat`, and the offline fallback — not only from the background loop,
+   * so a host that runs its own timer gets the same transitions. The listener
+   * runs synchronously inside that call; a listener that throws is ignored (see
+   * {@link emit}).
+   *
+   * `updateAvailable` is the one event that is not a licence transition: it
+   * carries an {@link UpdateInfo}, and subscribing to it is what makes the
+   * heartbeat ask the server whether a release is waiting.
+   */
+  on(event, listener) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    const fn = listener;
+    set.add(fn);
+    return () => {
+      set.delete(fn);
+    };
+  }
+  /**
+   * Adopt a verdict as the current one, announcing the transition it makes.
+   *
+   * The single funnel every path goes through, which is what makes the events
+   * trustworthy: a verdict reached anywhere else would be a transition nobody
+   * hears about.
+   */
+  adopt(state) {
+    const event = transitionEvent(this.current, state);
+    this.current = state;
+    if (event) this.emit(event, state);
+    return state;
+  }
+  emit(event, payload) {
+    for (const listener of this.listeners.get(event) ?? []) {
+      try {
+        listener(payload);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Run the check-ins the server's policy asks for, in the background.
+   *
+   * Two knobs have existed on the wire since Phase 1 and reached no client:
+   * `heartbeat_interval_s` (how often an install reports in — the telemetry
+   * rate, and the upper bound on how long a revocation takes to arrive) and
+   * `reval_after` (when the entitlement bag and the offline cache should be
+   * refreshed). Both are signed. This loop is what makes them a lever the
+   * developer can actually pull: change the policy, and deployed apps follow.
+   *
+   * One timer serves both. Each tick re-validates if the signed `reval_after`
+   * has passed, and otherwise sends a heartbeat — which is also what renews the
+   * cached verdict that {@link validate} falls back on, so an app that runs
+   * this stays inside its grace window without the host writing any scheduling
+   * of its own.
+   *
+   * Opt-in, and idempotent: calling it again replaces the running loop.
+   */
+  startCheckIns(opts = {}) {
+    this.stopCheckIns();
+    const generation = ++this.checkInGeneration;
+    const tick = async () => {
+      try {
+        const due = this.current?.revalidateAfter;
+        const state = due === null || due === void 0 || nowSeconds() >= due ? await this.validate() : await this.heartbeat();
+        if (generation !== this.checkInGeneration) return;
+        opts.onState?.(state);
+      } catch (e) {
+        if (generation !== this.checkInGeneration) return;
+        opts.onError?.(e);
+      }
+      if (generation === this.checkInGeneration) schedule();
+    };
+    const schedule = () => {
+      const secs = Math.max(60, this.heartbeatInterval ?? DEFAULT_HEARTBEAT_SECONDS);
+      this.checkInTimer = setTimeout(() => void tick(), secs * 1e3);
+      this.checkInTimer.unref?.();
+    };
+    schedule();
+  }
+  /** Stop the background check-ins started by {@link startCheckIns}. */
+  stopCheckIns() {
+    this.checkInGeneration += 1;
+    if (this.checkInTimer) {
+      clearTimeout(this.checkInTimer);
+      this.checkInTimer = null;
+    }
+  }
+  /** Drop the machine binding, in memory and on disk. */
+  forgetBinding() {
+    this.licenseKeyHash = null;
+    this.activationSecret = null;
+    this.machineId = null;
+    this.current = null;
+    this.binding = null;
+    this.store?.clear();
+  }
+  /** Merge fields into the persisted binding and write it back. */
+  persist(patch) {
+    if (!this.store || !this.binding) return;
+    this.binding = { ...this.binding, ...patch };
+    this.store.save(this.binding);
+  }
+  /**
+   * Advance the server-time high-water mark from a signed claim.
+   *
+   * Only ever forward: this is the mark that keeps offline grace bounded when
+   * the user owns the clock. `iat` is used when a token carries no explicit
+   * `server_time` (activation does not) — both are the server's clock, signed.
+   */
+  advanceClock(claims) {
+    const seen = num(claims["server_time"]) ?? num(claims["iat"]);
+    if (seen === null) return;
+    const current = this.binding?.timeHighWater ?? 0;
+    if (seen > current) {
+      if (this.binding) this.binding.timeHighWater = seen;
+    }
+  }
+  async validate() {
+    this.requireActivated();
+    try {
+      await this.ensureKeyset();
+      const nonce = newNonce();
+      const body = await this.post("/v1/client/validate", {
+        product_token: this.options.productToken,
+        fingerprint: { composite: this.fingerprint, components: this.fp.components },
+        activation_secret: this.activationSecret,
+        nonce,
+        // Sent here as well as on activation and heartbeat, because check-ins
+        // are opt-in and this call is not: an application that validates on
+        // launch and never calls `startCheckIns` would otherwise show, forever,
+        // whatever version it activated on.
+        app_version: this.options.appVersion,
+        sdk_version: SDK_ID
+      });
+      const token = body["validation_token"];
+      const claims = verifyToken(
+        this.licenseVerifyKeys(),
+        "validation",
+        this.options.productToken,
+        nonce,
+        token
+      );
+      const decision = typeof claims["decision"] === "string" ? claims["decision"] : "invalid";
+      this.advanceClock(claims);
+      this.persist({ validation: token, timeHighWater: this.binding?.timeHighWater });
+      return this.adopt(stateFromClaims(claims, decision, false));
+    } catch (e) {
+      if (e instanceof TalosApiError) throw e;
+      const offline = this.offlineDecision();
+      if (!offline) throw e;
+      return this.adopt(offline);
+    }
+  }
+  /**
+   * The verdict from the local cache, or null when there is nothing usable.
+   *
+   * This is the whole offline story, and every check here is load-bearing:
+   *
+   * - the token is re-verified under the pinned key, so a cache edited on disk
+   *   is worthless;
+   * - `fph` must be this machine, so copying a state file to a second computer
+   *   and pulling the network cable does not licence it;
+   * - `grace_until` — the policy's `offline_grace_hours`, signed — bounds how
+   *   long a verdict may outlive its issuance;
+   * - the licence's own expiry is re-checked, because a cached "valid" must not
+   *   outlive the subscription it was issued under;
+   * - and the clock is checked against a mark that only moves forward, since
+   *   every deadline above is evaluated against a clock the user controls.
+   */
+  offlineDecision() {
+    const token = this.binding?.validation;
+    if (!token) return null;
+    const now = nowSeconds();
+    const highWater = this.binding?.timeHighWater ?? 0;
+    if (highWater > 0 && now + CLOCK_SKEW_SECONDS2 < highWater) {
+      return new LicenseState("clock_tampered", {}, null, true, null, null);
+    }
+    let claims;
+    try {
+      claims = verifyCachedToken(
+        this.licenseVerifyKeys(),
+        "validation",
+        this.options.productToken,
+        token
+      );
+    } catch {
+      return null;
+    }
+    if (claims["fph"] !== this.fingerprint) return null;
+    const graceUntil = num(claims["grace_until"]);
+    const cached = stateFromClaims(
+      claims,
+      typeof claims["decision"] === "string" ? claims["decision"] : "invalid",
+      true
+    );
+    if (graceUntil === null || now > graceUntil) {
+      return new LicenseState(
+        "grace_expired",
+        cached.features,
+        cached.licenseExpiresAt,
+        true,
+        cached.revalidateAfter,
+        graceUntil
+      );
+    }
+    if (cached.licenseExpiresAt !== null && now > cached.licenseExpiresAt) {
+      return new LicenseState(
+        "expired",
+        cached.features,
+        cached.licenseExpiresAt,
+        true,
+        cached.revalidateAfter,
+        graceUntil
+      );
+    }
+    return cached;
+  }
+  async deactivate() {
+    this.requireActivated();
+    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();
+  }
+  /**
+   * Send a heartbeat: refreshes this machine's last-seen state, feeds the
+   * developer's monitoring (version adoption / active installs), and returns the
+   * current signed decision — so a revocation reaches the app within one
+   * heartbeat interval. Call it periodically while the app runs.
+   *
+   * The response is a signed `typ=heartbeat` token, so a MITM cannot forge the
+   * status or lengthen the interval.
+   */
+  /**
+   * The machine name to report, or `undefined` to report none.
+   *
+   * An explicit `""` means "do not send": omitting the field leaves whatever
+   * the server already holds, because the server coalesces, so sending an empty
+   * string would not clear it either — suppression has to happen here.
+   */
+  reportedHostname() {
+    const h = this.options.hostname ?? import_node_os3.default.hostname();
+    return h === "" ? void 0 : h;
+  }
+  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;
+  }
+  /** The channel this install follows; `stable` unless set. */
+  updateChannel() {
+    return this.options.updateChannel || "stable";
+  }
+  /**
+   * Act on the heartbeat's `upd` hint: confirm it with a real update check and
+   * emit `updateAvailable` for a release not announced yet.
+   *
+   * The hint is read from the **signed** claims, not the response envelope, and
+   * it is only ever a prompt to go and look: the check applies this install's
+   * anti-downgrade floor and verifies a manifest, neither of which the hint
+   * does. A hint that turns out to be wrong costs one request and emits
+   * nothing.
+   *
+   * A failing check is swallowed. The heartbeat it rode in on has already
+   * succeeded, and a licensing call must not start failing because the update
+   * service is having a bad day.
+   */
+  async announceUpdate(claims) {
+    if (!this.listeners.get("updateAvailable")?.size) return;
+    if (claims["upd"] !== true) return;
+    let info;
+    try {
+      info = await this.checkForUpdate();
+    } catch {
+      return;
+    }
+    if (!info || info.releaseSeq <= this.announcedReleaseSeq) return;
+    this.announcedReleaseSeq = info.releaseSeq;
+    this.emit("updateAvailable", info);
+  }
+  /**
+   * Acquire a floating seat (concurrent-use license). The server arbitrates the
+   * cap atomically, so this either returns a seat or throws
+   * {@link TalosApiError} with `seat_limit_reached` (HTTP 409).
+   *
+   * By default the seat is auto-renewed in the background at the server-chosen
+   * interval; a lost renewal invokes `onLeaseLost`. Always
+   * {@link releaseLease} on clean exit — a crash simply lets the seat expire.
+   */
+  async acquireLease(opts = {}) {
+    this.requireActivated();
+    await this.ensureKeyset();
+    const instanceId = opts.instanceId ?? this.instanceId;
+    const generation = this.leaseGeneration;
+    const nonce = newNonce();
+    const body = await this.post("/v1/client/leases", {
+      product_token: this.options.productToken,
+      fingerprint: { composite: this.fingerprint, components: this.fp.components },
+      activation_secret: this.activationSecret,
+      instance_id: instanceId,
+      nonce
+    });
+    const claims = verifyToken(
+      this.licenseVerifyKeys(),
+      "lease",
+      this.options.productToken,
+      nonce,
+      body["lease_token"]
+    );
+    if (claims["inst"] !== instanceId || claims["fph"] !== this.fingerprint) {
+      throw new TalosSignatureError("lease token does not match this instance");
+    }
+    const expiresAt = typeof claims["exp"] === "number" ? claims["exp"] : 0;
+    const serverNow = typeof claims["server_time"] === "number" ? claims["server_time"] : Math.floor(Date.now() / 1e3);
+    const budget = Math.max(1, expiresAt - serverNow);
+    const hinted = Number(body["renew_after_s"] ?? 0);
+    const lease = {
+      id: String(claims["lease"] ?? ""),
+      instanceId,
+      expiresAt,
+      renewAfterSeconds: hinted > 0 && hinted <= budget ? hinted : Math.max(1, Math.floor(budget / 3)),
+      seatsInUse: Number(claims["seats_in_use"] ?? 0),
+      maxSeats: Number(claims["max_seats"] ?? 0)
+    };
+    if (generation !== this.leaseGeneration) {
+      void this.releaseInstance(instanceId).catch(() => {
+      });
+      return lease;
+    }
+    this.lease = lease;
+    if (opts.autoRenew !== false) this.scheduleRenew(opts);
+    return lease;
+  }
+  /** Best-effort DELETE of one instance's seat (used for stale-renewal cleanup). */
+  async releaseInstance(instanceId) {
+    if (!this.activationSecret) return;
+    await this.request("DELETE", "/v1/client/leases", {
+      product_token: this.options.productToken,
+      fingerprint: { composite: this.fingerprint, components: this.fp.components },
+      activation_secret: this.activationSecret,
+      instance_id: instanceId
+    });
+  }
+  /** The currently held floating seat, if any. */
+  get currentLease() {
+    return this.lease;
+  }
+  /** Release the floating seat (clean exit) and stop auto-renewal. */
+  async releaseLease() {
+    this.leaseGeneration += 1;
+    this.stopRenew();
+    const lease = this.lease;
+    this.lease = null;
+    if (!lease) return;
+    await this.releaseInstance(lease.instanceId);
+  }
+  scheduleRenew(opts) {
+    this.stopRenew();
+    const generation = this.leaseGeneration;
+    const instanceId = this.lease?.instanceId;
+    const delay = Math.max(1, this.lease?.renewAfterSeconds ?? 200) * 1e3;
+    this.renewTimer = setTimeout(() => {
+      void (async () => {
+        try {
+          await this.acquireLease({ ...opts, instanceId, autoRenew: false });
+          if (generation !== this.leaseGeneration) return;
+          this.scheduleRenew(opts);
+        } catch (e) {
+          if (generation !== this.leaseGeneration) return;
+          this.lease = null;
+          opts.onLeaseLost?.(e instanceof Error ? e.message : "lease renewal failed");
+        }
+      })();
+    }, delay);
+    this.renewTimer.unref?.();
+  }
+  stopRenew() {
+    if (this.renewTimer) {
+      clearTimeout(this.renewTimer);
+      this.renewTimer = null;
+    }
+  }
+  /**
+   * Ask whether a newer release is available. Returns a verified {@link UpdateInfo}
+   * (all metadata comes from the manifest signed by the pinned release key), or
+   * `null` when up to date.
+   *
+   * Enforces anti-downgrade: a manifest whose `release_seq` is at or below the
+   * floor is rejected as no update. The floor is the persisted high-water mark
+   * — the highest `release_seq` this install has been seen running — unless
+   * {@link CheckForUpdateOptions.currentReleaseSeq} overrides it.
+   */
+  async checkForUpdate(opts = {}) {
+    this.requireActivated();
+    await this.ensureKeyset();
+    const body = await this.post("/v1/client/updates/check", {
+      product_token: this.options.productToken,
+      fingerprint: { composite: this.fingerprint, components: this.fp.components },
+      activation_secret: this.activationSecret,
+      current_version: opts.currentVersion ?? this.options.appVersion,
+      current_release_seq: this.releaseFloor(opts.currentReleaseSeq),
+      channel: opts.channel ?? this.updateChannel()
+    });
+    if (body["update_available"] !== true) return null;
+    const manifestToken = body["manifest"];
+    if (typeof manifestToken !== "string") {
+      throw new TalosSignatureError("update available but no manifest");
+    }
+    const m = verifyManifest(this.releaseVerifyKeys(), this.options.productToken, manifestToken);
+    const releaseSeq = typeof m["release_seq"] === "number" ? m["release_seq"] : 0;
+    const floor = this.releaseFloor(opts.currentReleaseSeq);
+    if (floor !== void 0 && releaseSeq <= floor) {
+      return null;
+    }
+    const downloads = /* @__PURE__ */ new Map();
+    for (const d of asArray(body["artifacts"])) {
+      const o = d;
+      if (typeof o["download_path"] === "string") {
+        downloads.set(selKey(o["platform"], o["arch"], o["kind"]), o["download_path"]);
+      }
+    }
+    const artifacts = asArray(m["artifacts"]).map((a) => {
+      const o = a;
+      const platform = String(o["platform"] ?? "");
+      const arch = String(o["arch"] ?? "");
+      const kind = String(o["kind"] ?? "");
+      return {
+        platform,
+        arch,
+        kind,
+        filename: String(o["filename"] ?? ""),
+        size: typeof o["size"] === "number" ? o["size"] : 0,
+        sha256: String(o["sha256"] ?? ""),
+        downloadPath: downloads.get(selKey(platform, arch, kind))
+      };
+    });
+    const deltaPaths = /* @__PURE__ */ new Map();
+    for (const d of asArray(body["deltas"])) {
+      const o = d;
+      if (typeof o["download_path"] === "string") {
+        deltaPaths.set(
+          deltaKey(o["platform"], o["arch"], o["from"], o["target_kind"]),
+          o["download_path"]
+        );
+      }
+    }
+    const deltas = asArray(m["deltas"]).map((d) => {
+      const o = d;
+      const t = o["target"] ?? {};
+      const platform = String(o["platform"] ?? "");
+      const arch = String(o["arch"] ?? "");
+      const from = String(o["from"] ?? "");
+      const targetKind = String(t["kind"] ?? "");
+      return {
+        platform,
+        arch,
+        from,
+        fromSeq: typeof o["from_seq"] === "number" ? o["from_seq"] : 0,
+        filename: String(o["filename"] ?? ""),
+        size: typeof o["size"] === "number" ? o["size"] : 0,
+        sha256: String(o["sha256"] ?? ""),
+        target: {
+          kind: targetKind,
+          filename: String(t["filename"] ?? ""),
+          size: typeof t["size"] === "number" ? t["size"] : 0,
+          sha256: String(t["sha256"] ?? "")
+        },
+        downloadPath: deltaPaths.get(deltaKey(platform, arch, from, targetKind))
+      };
+    });
+    return {
+      version: String(m["version"] ?? ""),
+      releaseSeq,
+      mandatory: m["mandatory"] === true,
+      notesUrl: typeof m["notes_url"] === "string" ? m["notes_url"] : null,
+      artifacts,
+      deltas
+    };
+  }
+  /**
+   * The patch that upgrades this machine, or `null` if there is none.
+   *
+   * Matches on the *exact* published version string, not on version ordering: a
+   * patch applies to the bytes it was built against, and "close enough" produces
+   * a corrupt file rather than an error. So a machine whose installed version is
+   * not one the release ships a patch from simply downloads the full build.
+   */
+  selectDelta(info, opts = {}) {
+    const from = opts.from ?? this.options.appVersion;
+    if (!from) return null;
+    const { platform, arch } = hostTarget();
+    const matches = info.deltas.filter(
+      (d) => d.platform === platform && d.arch === arch && d.from === from
+    );
+    if (opts.targetKind) return matches.find((d) => d.target.kind === opts.targetKind) ?? null;
+    return matches.length === 1 ? matches[0] : null;
+  }
+  /**
+   * Download a patch and verify its bytes against the manifest's SHA-256, then
+   * write it to `destPath`. Returns the patch, whose `target.sha256` is what the
+   * rebuilt file must hash to.
+   *
+   * Does NOT apply it. Applying is the host's job — and so is checking the
+   * result, which {@link verifyAppliedUpdate} does. A patch verified on the way
+   * in and a result nobody checks is a signed chain that stops one step short of
+   * the binary that runs.
+   */
+  async downloadDelta(info, destPath, opts = {}) {
+    const chosen = opts.delta ?? this.selectDelta(info, opts);
+    if (!chosen) throw new TalosError("no patch applies to this install");
+    await this.fetchVerified(
+      chosen.downloadPath,
+      chosen.size,
+      chosen.sha256,
+      destPath,
+      opts.onProgress
+    );
+    this.rememberDownloaded(info);
+    return chosen;
+  }
+  /**
+   * Download one artifact of an update and verify its bytes against the manifest
+   * SHA-256, then write it to `destPath`. Returns the chosen artifact. Does NOT
+   * apply or execute anything — verification and installation are the host app's
+   * responsibility.
+   *
+   * `onProgress` is called as the bytes arrive, which is the only way a host can
+   * show a bar: an installer takes minutes on a domestic connection, and a
+   * promise that says nothing until it settles is indistinguishable from one that
+   * has hung. Totals come from the signed manifest — see {@link DownloadProgress}.
+   */
+  async downloadUpdate(info, destPath, artifact, onProgress) {
+    this.requireActivated();
+    const chosen = artifact ?? pickArtifact(info.artifacts);
+    if (!chosen) throw new TalosError("no artifact matches this platform");
+    await this.fetchVerified(chosen.downloadPath, chosen.size, chosen.sha256, destPath, onProgress);
+    this.rememberDownloaded(info);
+    return chosen;
+  }
+  /**
+   * Note which release's bytes are now on disk, so the next start can tell
+   * whether they were installed.
+   *
+   * Written after the hash check, never before: a download that failed
+   * verification is not a release this install is about to be running, and
+   * recording it would let a corrupt or substituted file raise the
+   * anti-downgrade floor past a good build.
+   */
+  rememberDownloaded(info) {
+    if (info.releaseSeq <= (this.binding?.releaseSeqHighWater ?? 0)) return;
+    this.persist({ pendingRelease: { version: info.version, releaseSeq: info.releaseSeq } });
+  }
+  /**
+   * Fetch one file over the entitled download route and put it at `destPath`
+   * only once its bytes match the size and hash the signed manifest names.
+   * Shared by full builds and patches, which differ in what they are for and not
+   * at all in how their bytes are checked.
+   *
+   * The bytes go straight to a `.talos-part` file beside the destination, hashed
+   * as they arrive, and are renamed into place only once the hash matches. Two
+   * things follow. A multi-gigabyte installer is never held in memory — the whole
+   * body used to be buffered before it was checked, so the largest artifact a
+   * product could ship was bounded by the smallest machine it ran on. And
+   * `destPath` never holds unverified bytes, not even briefly: a download that
+   * fails leaves whatever was there before rather than a truncated file a host
+   * might run.
+   */
+  async fetchVerified(downloadPath, size, sha256, destPath, onProgress) {
+    if (!downloadPath) throw new TalosError("artifact has no download path");
+    const url = this.options.serverUrl.replace(/\/+$/, "") + downloadPath;
+    const res = await this.doFetch(url, {
+      method: "GET",
+      headers: {
+        "x-talos-product-token": this.options.productToken,
+        "x-talos-activation-secret": this.activationSecret,
+        "x-talos-fingerprint": this.fingerprint
+      }
+    });
+    if (res.status < 200 || res.status >= 300) throw new TalosApiError(res.status, void 0);
+    const contentLength = res.headers?.get("content-length");
+    if (contentLength && Number(contentLength) > size) {
+      throw new TalosSignatureError("artifact exceeds manifest size");
+    }
+    const partPath = destPath + ".talos-part";
+    const handle = await (0, import_promises.open)(partPath, "w");
+    const hash = (0, import_node_crypto5.createHash)("sha256");
+    let received = 0;
+    let closed = false;
+    const take = async (chunk) => {
+      received += chunk.byteLength;
+      if (received > size) throw new TalosSignatureError("artifact exceeds manifest size");
+      hash.update(chunk);
+      await handle.write(chunk);
+      onProgress?.({ bytesReceived: received, totalBytes: size });
+    };
+    try {
+      const body = res.body;
+      if (body) {
+        const reader = body.getReader();
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done || !value) break;
+            await take(value);
+          }
+        } catch (e) {
+          await reader.cancel().catch(() => {
+          });
+          throw e;
+        }
+      } else {
+        await take(new Uint8Array(await res.arrayBuffer()));
+      }
+      if (hash.digest("hex") !== sha256) {
+        throw new TalosSignatureError("artifact hash mismatch (tampered or wrong bytes)");
+      }
+      await handle.close();
+      closed = true;
+      await (0, import_promises.rename)(partPath, destPath);
+    } catch (e) {
+      if (!closed) await handle.close().catch(() => {
+      });
+      await (0, import_promises.rm)(partPath, { force: true }).catch(() => {
+      });
+      throw e;
+    }
+  }
+  requireActivated() {
+    if (!this.activationSecret) {
+      throw new TalosError("not activated: call activate() first");
+    }
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  /**
+   * The abort signal for one licensing call, or `undefined` when disabled.
+   *
+   * A fresh one per request rather than one shared: `AbortSignal.timeout`
+   * starts counting when it is created, so a signal made once in the
+   * constructor would already have fired by the second call.
+   */
+  timeoutSignal() {
+    const ms = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    if (!ms || ms <= 0) return void 0;
+    return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+  }
+  async request(method, path, body) {
+    let res;
+    try {
+      res = await this.doFetch(this.options.serverUrl.replace(/\/+$/, "") + path, {
+        method,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: this.timeoutSignal()
+      });
+    } catch (e) {
+      if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+        throw new TalosError(
+          `request timed out after ${this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS}ms`
+        );
+      }
+      throw e;
+    }
+    const text = await res.text();
+    if (res.status < 200 || res.status >= 300) {
+      let errorCode;
+      try {
+        errorCode = JSON.parse(text).error;
+      } catch {
+        errorCode = void 0;
+      }
+      throw new TalosApiError(res.status, errorCode);
+    }
+    return text ? JSON.parse(text) : {};
+  }
+};
+function stateFromClaims(claims, decision, isOffline) {
+  const lic = claims["lic"] ?? {};
+  const features = lic["features"] ?? {};
+  const exp = num(lic["lic_exp"]);
+  const iat = num(claims["iat"]) ?? nowSeconds();
+  const revalAfter = num(claims["reval_after"]) ?? hoursAfter(iat, lic["reval_h"]);
+  const graceUntil = num(claims["grace_until"]) ?? hoursAfter(iat, lic["grace_h"]);
+  return new LicenseState(decision, features, exp, isOffline, revalAfter, graceUntil);
+}
+function hoursAfter(base, hours) {
+  const h = num(hours);
+  return h === null ? null : base + h * 3600;
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function nowSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function transitionEvent(prev, next) {
+  if (next.decision === "clock_tampered") {
+    return prev?.decision === "clock_tampered" ? null : "clockTamperDetected";
+  }
+  if (next.decision === "grace_expired") {
+    return prev?.decision === "grace_expired" ? null : "gracePeriodExpired";
+  }
+  if (next.isValid) {
+    if (!next.isOffline) return null;
+    return prev?.isOffline && prev.isValid ? null : "gracePeriodStarted";
+  }
+  return prev?.decision === next.decision ? null : "licenseInvalid";
+}
+function newNonce() {
+  return b64urlEncode((0, import_node_crypto5.randomBytes)(16));
+}
+function asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+function selKey(platform, arch, kind) {
+  return `${String(platform)}/${String(arch)}/${String(kind)}`;
+}
+function deltaKey(platform, arch, from, targetKind) {
+  return `${String(platform)}/${String(arch)}/${String(from)}/${String(targetKind)}`;
+}
+function hostTarget() {
+  const map = { win32: "windows", darwin: "macos", linux: "linux" };
+  return { platform: map[import_node_os3.default.platform()] ?? import_node_os3.default.platform(), arch: import_node_os3.default.arch() };
+}
+function pickArtifact(artifacts) {
+  const { platform, arch } = hostTarget();
+  const matches = artifacts.filter((a) => a.platform === platform && a.arch === arch);
+  return matches.find((a) => a.kind === "installer") ?? matches[0];
+}
+async function verifyAppliedUpdate(filePath, delta) {
+  const hash = (0, import_node_crypto5.createHash)("sha256");
+  const stream = (0, import_node_fs3.createReadStream)(filePath);
+  await new Promise((resolve, reject) => {
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve());
+  });
+  const actual = hash.digest("hex");
+  if (actual !== delta.target.sha256) {
+    throw new TalosSignatureError(
+      `applied update does not match the signed manifest: expected ${delta.target.sha256}, got ${actual}`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LicenseState,
+  StateStore,
+  TalosApiError,
+  TalosClient,
+  TalosError,
+  TalosSignatureError,
+  collectFingerprint,
+  defaultStatePath,
+  hashLicenseKey,
+  publicKeyFromBase64,
+  verifyAppliedUpdate,
+  verifyKeyset,
+  verifyManifest,
+  verifyToken
+});
+//# sourceMappingURL=index.cjs.map