@antondziuin/talos-sdk 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/client.ts
 import { createHash as createHash3, randomBytes as randomBytes2 } from "crypto";
-import { createReadStream } from "fs";
+import { createReadStream, readFileSync as readFileSync3 } from "fs";
 import { open, rename, rm } from "fs/promises";
 import os3 from "os";
 import "crypto";
@@ -189,7 +189,13 @@ var StateStore = class {
       if (pending && typeof pending["version"] === "string" && typeof pending["releaseSeq"] === "number") {
         b.pendingRelease = { version: pending["version"], releaseSeq: pending["releaseSeq"] };
       }
-      return b.activationSecret ? b : null;
+      if (typeof o["machineKey"] === "string") b.machineKey = o["machineKey"];
+      if (typeof o["machinePublicKey"] === "string") {
+        b.machinePublicKey = o["machinePublicKey"];
+      }
+      if (typeof o["offlineToken"] === "string") b.offlineToken = o["offlineToken"];
+      if (typeof o["offlineSeen"] === "number") b.offlineSeen = o["offlineSeen"];
+      return b.activationSecret || b.offlineToken || b.machineKey ? b : null;
     } catch {
       return null;
     }
@@ -230,9 +236,51 @@ var StateStore = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.1";
 var SDK_ID = `node/${SDK_VERSION}`;
 
+// src/diagnostics.ts
+var decisions = /* @__PURE__ */ new Set(["valid", "expired", "revoked", "suspended", "deactivated", "machine_revoked", "invalid", "grace_expired", "clock_tampered"]);
+var errors = /* @__PURE__ */ new Set(["product_not_found", "license_not_found", "license_expired", "license_revoked", "license_suspended", "machine_revoked", "activation_limit_reached", "seat_limit_reached", "deactivation_limit_reached", "tenant_suspended", "tenant_closed", "invalid_activation_secret", "rate_limited"]);
+function diagnosticReport(activated, anchorPinned, state, error) {
+  const code = error instanceof TalosApiError ? errors.has(error.errorCode ?? "") ? error.errorCode : "api_error" : error instanceof TalosSignatureError ? "signature_verification_failed" : error != null ? "client_error" : null;
+  const decision = state == null ? null : decisions.has(state.decision) ? state.decision : "unknown";
+  const advice = {
+    signature_verification_failed: "Check the pinned anchor, product configuration and system time. Keep signature verification enabled.",
+    activation_limit_reached: "Open the license's devices in the portal. Release an unused device or review its activation limit.",
+    seat_limit_reached: "Close an unused app session or review the concurrent seat limit.",
+    license_expired: "Renew the license in the portal, then validate again.",
+    expired: "Renew the license in the portal, then validate again.",
+    license_revoked: "Revocation is permanent. Ask the vendor for a replacement license.",
+    revoked: "Revocation is permanent. Ask the vendor for a replacement license.",
+    license_suspended: "Ask the vendor to review the suspension before activating a new device.",
+    suspended: "Ask the vendor to review the suspension.",
+    machine_revoked: "Ask the vendor to review this device in the portal.",
+    grace_expired: "Reconnect to the configured Talos server and validate. Do not extend the local grace deadline.",
+    clock_tampered: "Correct the system clock and validate online.",
+    client_error: "Check connectivity, server configuration and local state access. The exception text is intentionally excluded."
+  };
+  const action = advice[code ?? decision ?? ""] ?? (code ? "Review the licensing call and configuration with the vendor. HTTP errors are not signed license decisions." : state?.isOffline ? "The last decision was offline. Check connectivity and validate online; this snapshot cannot identify the transport failure." : !activated ? "Activate with a license key, then validate the saved activation." : decision === "valid" ? "The last licensing call returned valid. Check the portal for this device's recorded validation." : "Run a licensing check and generate a new report. Ask the vendor to review an invalid decision.");
+  const timestamp = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+  return JSON.stringify({
+    schema_version: 1,
+    sdk: SDK_ID,
+    generated_at: Math.floor(Date.now() / 1e3),
+    activated,
+    anchor_pinned: anchorPinned,
+    decision,
+    is_offline: state?.isOffline ?? null,
+    license_expires_at: timestamp(state?.licenseExpiresAt),
+    grace_until: timestamp(state?.graceUntil),
+    error_code: code,
+    http_status: error instanceof TalosApiError && Number.isInteger(error.statusCode) && error.statusCode >= 100 && error.statusCode <= 599 ? error.statusCode : null,
+    next_action: action
+  }, null, 2);
+}
+
+// src/offline.ts
+import { createPrivateKey, generateKeyPairSync, sign as cryptoSign } from "crypto";
+
 // src/talos-compact.ts
 import { createPublicKey, verify as cryptoVerify } from "crypto";
 var SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
@@ -312,6 +360,36 @@ function verifyKeyset(anchorKey, expectedAud, token) {
   return claims;
 }
 
+// src/offline.ts
+var REQUEST_DOMAIN = "talos-offline-request";
+var RECEIPT_DOMAIN = "talos-offline-deactivation";
+var LICENSE_FILE_KIND = "talos-offline-license";
+var DOC_VERSION = 1;
+function generateMachineKey() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  return {
+    privateKey: privateKey.export({ format: "der", type: "pkcs8" }).toString("base64"),
+    // The raw key is the last 32 bytes of the SPKI DER; every other Ed25519
+    // implementation in this project speaks raw-32, including the server's.
+    publicKey: publicKey.export({ format: "der", type: "spki" }).subarray(-32).toString("base64")
+  };
+}
+function privateKeyObject(pkcs8Base64) {
+  return createPrivateKey({
+    key: Buffer.from(pkcs8Base64, "base64"),
+    format: "der",
+    type: "pkcs8"
+  });
+}
+function signedMessage(domain, payloadB64) {
+  return `${domain}.${DOC_VERSION}.${payloadB64}`;
+}
+function signMachineDoc(key, domain, payload) {
+  const req = b64urlEncode(Buffer.from(JSON.stringify(payload), "utf8"));
+  const sig = cryptoSign(null, Buffer.from(signedMessage(domain, req), "ascii"), privateKeyObject(key.privateKey));
+  return { v: DOC_VERSION, kind: domain, req, sig: b64urlEncode(sig) };
+}
+
 // src/client.ts
 var CLOCK_SKEW_SECONDS2 = 60;
 var DEFAULT_HEARTBEAT_SECONDS = 600;
@@ -398,6 +476,14 @@ var TalosClient = class {
   /** Default instance id for floating leases: one per client object. */
   instanceId = b64urlEncode(randomBytes2(9));
   current = null;
+  /**
+   * Return a local JSON support report without credentials, identifiers or
+   * exception text. Pass a caught error for classification. Makes no requests
+   * and does not change licensing state; `decision` is the last known result.
+   */
+  createDiagnosticReport(error) {
+    return diagnosticReport(this.isActivated, this.options.anchorPublicKey != null && this.options.anchorPublicKey !== "", this.current, error);
+  }
   listeners = /* @__PURE__ */ new Map();
   /** The newest release this client has already announced. */
   announcedReleaseSeq = 0;
@@ -423,9 +509,9 @@ var TalosClient = class {
     const stored = this.store?.load() ?? null;
     if (stored) {
       this.binding = stored;
-      this.licenseKeyHash = stored.licenseKeyHash;
-      this.activationSecret = stored.activationSecret;
-      this.machineId = stored.machineId;
+      this.licenseKeyHash = stored.licenseKeyHash || null;
+      this.activationSecret = stored.activationSecret || null;
+      this.machineId = stored.machineId || null;
       if (stored.keyset) {
         try {
           this.adoptKeyset(stored.keyset);
@@ -473,8 +559,17 @@ var TalosClient = class {
    * construction, so this is the startup question: prompt for a licence key, or
    * go straight to {@link validate}?
    */
+  /**
+   * Whether this install holds a licence for this machine.
+   *
+   * True for an online activation (the activation secret is held) **and** for an
+   * air-gapped install that has loaded a licence file. Widened rather than
+   * split, because what a host does with this is decide whether to ask the user
+   * for a licence key — and an air-gapped machine that already holds a valid
+   * file must not be asked for one it has no way to redeem.
+   */
   get isActivated() {
-    return this.activationSecret !== null;
+    return this.activationSecret !== null || this.binding?.offlineToken != null;
   }
   /** The server's id for this machine, once activated. */
   get currentMachineId() {
@@ -631,12 +726,221 @@ var TalosClient = class {
       // 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
+      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.
+   *
+   * The air-gapped counterpart of the activation secret: a machine that cannot
+   * reach a server is never issued one, so it makes an identity of its own and
+   * the vendor binds the file to it.
+   */
+  machineKey() {
+    const held = this.binding?.machineKey;
+    const pub = this.binding?.machinePublicKey;
+    if (held && pub) return { privateKey: held, publicKey: pub };
+    const key = generateMachineKey();
+    this.binding = {
+      ...this.bindingBase(),
+      machineKey: key.privateKey,
+      machinePublicKey: key.publicKey
+    };
+    this.store?.save(this.binding);
+    return key;
+  }
+  /**
+   * The binding as it stands, or an empty one to build on.
+   *
+   * An air-gapped install reaches its first write with nothing stored — no
+   * licence key, no activation secret, no machine id — so there has to be
+   * something for the offline fields to be added to.
+   */
+  bindingBase() {
+    return this.binding ?? {
+      licenseKeyHash: "",
+      activationSecret: "",
+      machineId: "",
+      fingerprint: this.fingerprint
+    };
+  }
+  /**
+   * Write the request an air-gapped machine hands to its vendor.
+   *
+   * Save the returned object as `talos-request.json`, carry it to whoever sold
+   * the licence, and they upload it in the portal. What comes back is a
+   * `license.talos` for {@link loadOfflineLicense} — and only for *this*
+   * machine: the request carries the fingerprint and the public half of a
+   * keypair generated here, and the file is bound to both.
+   *
+   * Calling it twice produces two requests under the same identity. The vendor
+   * can issue against either; the second file supersedes the first without
+   * spending a second seat.
+   *
+   * ```ts
+   * writeFileSync("talos-request.json", JSON.stringify(talos.createOfflineRequest(), null, 2));
+   * ```
+   *
+   * @param licenseKey Optional. The operator picks the licence in the portal, so
+   * it is not needed — but when it is present the server checks it against the
+   * licence being issued against, which catches issuing from the wrong tab.
+   */
+  createOfflineRequest(licenseKey) {
+    const key = this.machineKey();
+    return signMachineDoc(key, REQUEST_DOMAIN, {
+      product_token: this.options.productToken,
+      license_key: licenseKey,
+      fingerprint: { composite: this.fingerprint, components: this.fp.components },
+      machine_pubkey: key.publicKey,
+      nonce: newNonce(),
+      hostname: this.reportedHostname(),
+      os: `${os3.type()} ${os3.release()}`,
+      arch: os3.arch(),
+      app_version: this.options.appVersion,
+      sdk_version: SDK_ID,
+      created_at: nowSeconds()
+    });
+  }
+  /**
+   * Adopt an air-gapped licence file issued for this machine.
+   *
+   * 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.
+   *
+   * **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*
+   * one but cannot license this machine right now comes back as a verdict —
+   * `machine_mismatch` for another machine's file, `offline_file_expired` for
+   * one past its horizon, `expired` for a licence that has ended, and
+   * `clock_tampered` for a clock wound back behind what this install has already
+   * seen. Those are things the user can be told and can act on, and turning
+   * them into exceptions would make the launch path throw for a reason nobody
+   * can catch usefully.
+   */
+  async loadOfflineLicense(pathOrBuffer) {
+    const raw = typeof pathOrBuffer === "string" ? readFileSync3(pathOrBuffer) : Buffer.from(pathOrBuffer);
+    let doc;
+    try {
+      doc = JSON.parse(raw.toString("utf8"));
+    } catch {
+      throw new TalosError("not a Talos offline licence file");
+    }
+    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"]);
+  }
+  /**
+   * Hand this machine's air-gapped seat back.
+   *
+   * Save the returned object as `talos-deactivation.json` and send it to the
+   * vendor; they upload it in the portal and the seat returns to the pool.
+   * Signed by the same key the licence file is bound to, which is what makes it
+   * worth anything to a server that has never spoken to this machine.
+   *
+   * **The licence is dropped here, before the document is returned** — so an
+   * application that writes the file, or loses it, or never sends it has still
+   * stopped using the seat it is giving up. A receipt proves intent, not
+   * destruction: the vendor's copy of the file cannot be recalled, and if this
+   * machine is later restored from a snapshot it keeps working until that file
+   * expires. That is the accepted cost, and it is why the horizon is short.
+   *
+   * Throws when this install holds no offline licence — there is nothing to hand
+   * back, and a document saying otherwise would be a lie the vendor acts on.
+   */
+  createOfflineDeactivation() {
+    const token = this.binding?.offlineToken;
+    const key = this.binding?.machineKey;
+    const pub = this.binding?.machinePublicKey;
+    if (!token || !key || !pub) {
+      throw new TalosError("no offline licence to hand back");
+    }
+    let claims;
+    try {
+      claims = verifyCachedToken(
+        this.licenseVerifyKeys(),
+        "offline",
+        this.options.productToken,
+        token
+      );
+    } catch {
+      throw new TalosError("the stored offline licence no longer verifies");
+    }
+    this.binding = { ...this.bindingBase(), offlineToken: void 0 };
+    this.current = null;
+    this.store?.save(this.binding);
+    return signMachineDoc({ privateKey: key, publicKey: pub }, RECEIPT_DOMAIN, {
+      fid: claims["fid"],
+      mid: claims["mid"],
+      fph: this.fingerprint,
+      local_time: nowSeconds()
+    });
+  }
+  /**
+   * Verify the offline file against this machine and this clock, and adopt the
+   * verdict. Runs on load and again on every {@link validate}, because the two
+   * things that can change afterwards — the clock and the calendar — are
+   * exactly what it checks.
+   */
+  adoptOfflineToken(token, keyset) {
+    const claims = verifyCachedToken(
+      this.licenseVerifyKeys(),
+      "offline",
+      this.options.productToken,
+      token
+    );
+    const mismatch = () => this.adopt(new LicenseState("machine_mismatch", {}, null, true, null, null));
+    if (typeof claims["mpk"] !== "string" || claims["mpk"] !== this.binding?.machinePublicKey) {
+      return mismatch();
+    }
+    if (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;
+    const base = this.bindingBase();
+    this.binding = {
+      ...base,
+      machineId: this.machineId ?? base.machineId,
+      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));
+  }
   /**
    * 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
@@ -776,6 +1080,9 @@ var TalosClient = class {
     }
   }
   async validate() {
+    if (!this.activationSecret && this.binding?.offlineToken) {
+      return this.adoptOfflineToken(this.binding.offlineToken);
+    }
     this.requireActivated();
     try {
       await this.ensureKeyset();
@@ -1444,7 +1751,10 @@ async function verifyAppliedUpdate(filePath, delta) {
   }
 }
 export {
+  LICENSE_FILE_KIND,
   LicenseState,
+  RECEIPT_DOMAIN,
+  REQUEST_DOMAIN,
   StateStore,
   TalosApiError,
   TalosClient,