@antondziuin/talos-sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,46 @@
 import { KeyObject } from 'node:crypto';
 
+/**
+ * The air-gapped exchange, and the identity that makes it possible.
+ *
+ * Online, a machine proves who it is with the `activation_secret` the server
+ * hands back from `activate`. A machine that cannot reach a server never gets
+ * one — so it makes its own: an Ed25519 pair at the first offline request,
+ * public half in `talos-request.json`, private half never leaving this disk. The
+ * file the portal issues is bound to that key as well as to the fingerprint, and
+ * anything this machine sends back afterwards is signed by it.
+ *
+ * The document format deliberately is **not** Talos-compact. That format's `typ`
+ * set is the closed list of things the *platform* signs, and putting a machine's
+ * key into the same namespace as a product's is exactly the confusion the tag
+ * set exists to prevent. What is copied is the part that matters: the payload
+ * travels base64url-encoded and is verified as received, never re-serialised, so
+ * three implementations cannot disagree about JSON key order and turn that into
+ * a signature one of them rejects.
+ */
+/** Domain tag of `talos-request.json`; also part of what is signed. */
+declare const REQUEST_DOMAIN = "talos-offline-request";
+/**
+ * Domain tag of `talos-deactivation.json`, the document that hands a seat back.
+ *
+ * The second thing a machine key signs, and the reason the domain is inside the
+ * signed bytes rather than beside them: without it a captured request would be a
+ * valid receipt for the same machine, and returning a seat is not what its owner
+ * asked for when they asked for a licence.
+ */
+declare const RECEIPT_DOMAIN = "talos-offline-deactivation";
+/** `kind` of the file the portal issues back. */
+declare const LICENSE_FILE_KIND = "talos-offline-license";
+/** A document this machine signed: what gets written to disk and carried. */
+interface SignedDoc {
+    v: number;
+    kind: string;
+    /** base64url of the payload JSON. */
+    req: string;
+    /** base64url Ed25519 signature over `"<kind>.1.<req>"`. */
+    sig: string;
+}
+
 /**
  * What a response has to offer this SDK.
  *
@@ -428,6 +469,12 @@ declare class TalosClient {
     /** Default instance id for floating leases: one per client object. */
     private readonly instanceId;
     current: LicenseState | 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?: unknown): string;
     private readonly listeners;
     /** The newest release this client has already announced. */
     private announcedReleaseSeq;
@@ -462,6 +509,15 @@ declare class TalosClient {
      * 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(): boolean;
     /** The server's id for this machine, once activated. */
     get currentMachineId(): string | null;
@@ -528,6 +584,90 @@ declare class TalosClient {
      * elsewhere.
      */
     activate(licenseKey: string): Promise<LicenseState>;
+    /**
+     * 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.
+     */
+    private machineKey;
+    /**
+     * 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.
+     */
+    private bindingBase;
+    /**
+     * 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?: string): SignedDoc;
+    /**
+     * 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.
+     */
+    loadOfflineLicense(pathOrBuffer: string | Buffer | Uint8Array): Promise<LicenseState>;
+    /**
+     * 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(): SignedDoc;
+    /**
+     * 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.
+     */
+    private adoptOfflineToken;
     /**
      * 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
@@ -912,6 +1052,42 @@ interface StoredBinding {
         version: string;
         releaseSeq: number;
     };
+    /**
+     * This machine's own Ed25519 private key (PKCS#8 DER, base64), generated at
+     * its first offline request.
+     *
+     * The air-gapped counterpart of `activationSecret`, and it exists for the same
+     * reason that one does: an install has to be able to prove it is the install a
+     * decision was made for. It never leaves this file — only the public half
+     * travels, inside `talos-request.json` — and losing the file means repeating
+     * the ceremony with the vendor, because the identity has exactly one copy by
+     * construction.
+     */
+    machineKey?: string;
+    /** The raw public half, standard base64. Checked against the file's `mpk`. */
+    machinePublicKey?: string;
+    /** The last verified `typ=offline` licence file. */
+    offlineToken?: string;
+    /**
+     * The highest local clock ever seen while running on an offline file, in unix
+     * seconds.
+     *
+     * Deliberately separate from {@link timeHighWater}, which holds *server*
+     * times taken from signed claims. An air-gapped install sees exactly one
+     * server time in its life — the `iat` of its file — so the server mark stops
+     * moving, and nothing would notice a clock wound back to the day after
+     * issuance to keep a year-long file alive forever.
+     *
+     * Mixing the two would be worse than useless: a machine whose clock ran fast
+     * would inflate the server mark, and correcting the clock afterwards would
+     * then read as tampering on an install that had done nothing wrong.
+     *
+     * What this bounds is **rollback, not freeze**. A user who stops their clock
+     * keeps a file past its expiry; a user who winds it back is told
+     * `clock_tampered`. That is the honest limit of enforcing a deadline against
+     * a clock its owner controls, and it is the price of offline.
+     */
+    offlineSeen?: number;
 }
 /**
  * Where the binding lives, per product, following each OS's convention.
@@ -982,4 +1158,4 @@ declare function verifyManifest(releaseKeys: Keys, expectedAud: string, token: s
  */
 declare function verifyKeyset(anchorKey: KeyObject, expectedAud: string, token: string): Record<string, unknown>;
 
-export { type AcquireLeaseOptions, type CheckForUpdateOptions, type CheckInOptions, type DeltaOptions, type DownloadProgress, type DownloadProgressCallback, type FetchLike, type FetchResponseLike, type FingerprintData, type Lease, type LicenseListener, LicenseState, StateStore, type StoredBinding, TalosApiError, TalosClient, TalosError, type TalosEventMap, type TalosEventName, type TalosOptions, TalosSignatureError, type UpdateArtifact, type UpdateDelta, type UpdateDeltaTarget, type UpdateInfo, collectFingerprint, defaultStatePath, hashLicenseKey, publicKeyFromBase64, verifyAppliedUpdate, verifyKeyset, verifyManifest, verifyToken };
+export { type AcquireLeaseOptions, type CheckForUpdateOptions, type CheckInOptions, type DeltaOptions, type DownloadProgress, type DownloadProgressCallback, type FetchLike, type FetchResponseLike, type FingerprintData, LICENSE_FILE_KIND, type Lease, type LicenseListener, LicenseState, RECEIPT_DOMAIN, REQUEST_DOMAIN, type SignedDoc, StateStore, type StoredBinding, TalosApiError, TalosClient, TalosError, type TalosEventMap, type TalosEventName, type TalosOptions, TalosSignatureError, type UpdateArtifact, type UpdateDelta, type UpdateDeltaTarget, type UpdateInfo, collectFingerprint, defaultStatePath, hashLicenseKey, publicKeyFromBase64, verifyAppliedUpdate, verifyKeyset, verifyManifest, verifyToken };

package/dist/index.d.ts

@@ -1,5 +1,46 @@
 import { KeyObject } from 'node:crypto';
 
+/**
+ * The air-gapped exchange, and the identity that makes it possible.
+ *
+ * Online, a machine proves who it is with the `activation_secret` the server
+ * hands back from `activate`. A machine that cannot reach a server never gets
+ * one — so it makes its own: an Ed25519 pair at the first offline request,
+ * public half in `talos-request.json`, private half never leaving this disk. The
+ * file the portal issues is bound to that key as well as to the fingerprint, and
+ * anything this machine sends back afterwards is signed by it.
+ *
+ * The document format deliberately is **not** Talos-compact. That format's `typ`
+ * set is the closed list of things the *platform* signs, and putting a machine's
+ * key into the same namespace as a product's is exactly the confusion the tag
+ * set exists to prevent. What is copied is the part that matters: the payload
+ * travels base64url-encoded and is verified as received, never re-serialised, so
+ * three implementations cannot disagree about JSON key order and turn that into
+ * a signature one of them rejects.
+ */
+/** Domain tag of `talos-request.json`; also part of what is signed. */
+declare const REQUEST_DOMAIN = "talos-offline-request";
+/**
+ * Domain tag of `talos-deactivation.json`, the document that hands a seat back.
+ *
+ * The second thing a machine key signs, and the reason the domain is inside the
+ * signed bytes rather than beside them: without it a captured request would be a
+ * valid receipt for the same machine, and returning a seat is not what its owner
+ * asked for when they asked for a licence.
+ */
+declare const RECEIPT_DOMAIN = "talos-offline-deactivation";
+/** `kind` of the file the portal issues back. */
+declare const LICENSE_FILE_KIND = "talos-offline-license";
+/** A document this machine signed: what gets written to disk and carried. */
+interface SignedDoc {
+    v: number;
+    kind: string;
+    /** base64url of the payload JSON. */
+    req: string;
+    /** base64url Ed25519 signature over `"<kind>.1.<req>"`. */
+    sig: string;
+}
+
 /**
  * What a response has to offer this SDK.
  *
@@ -428,6 +469,12 @@ declare class TalosClient {
     /** Default instance id for floating leases: one per client object. */
     private readonly instanceId;
     current: LicenseState | 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?: unknown): string;
     private readonly listeners;
     /** The newest release this client has already announced. */
     private announcedReleaseSeq;
@@ -462,6 +509,15 @@ declare class TalosClient {
      * 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(): boolean;
     /** The server's id for this machine, once activated. */
     get currentMachineId(): string | null;
@@ -528,6 +584,90 @@ declare class TalosClient {
      * elsewhere.
      */
     activate(licenseKey: string): Promise<LicenseState>;
+    /**
+     * 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.
+     */
+    private machineKey;
+    /**
+     * 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.
+     */
+    private bindingBase;
+    /**
+     * 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?: string): SignedDoc;
+    /**
+     * 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.
+     */
+    loadOfflineLicense(pathOrBuffer: string | Buffer | Uint8Array): Promise<LicenseState>;
+    /**
+     * 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(): SignedDoc;
+    /**
+     * 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.
+     */
+    private adoptOfflineToken;
     /**
      * 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
@@ -912,6 +1052,42 @@ interface StoredBinding {
         version: string;
         releaseSeq: number;
     };
+    /**
+     * This machine's own Ed25519 private key (PKCS#8 DER, base64), generated at
+     * its first offline request.
+     *
+     * The air-gapped counterpart of `activationSecret`, and it exists for the same
+     * reason that one does: an install has to be able to prove it is the install a
+     * decision was made for. It never leaves this file — only the public half
+     * travels, inside `talos-request.json` — and losing the file means repeating
+     * the ceremony with the vendor, because the identity has exactly one copy by
+     * construction.
+     */
+    machineKey?: string;
+    /** The raw public half, standard base64. Checked against the file's `mpk`. */
+    machinePublicKey?: string;
+    /** The last verified `typ=offline` licence file. */
+    offlineToken?: string;
+    /**
+     * The highest local clock ever seen while running on an offline file, in unix
+     * seconds.
+     *
+     * Deliberately separate from {@link timeHighWater}, which holds *server*
+     * times taken from signed claims. An air-gapped install sees exactly one
+     * server time in its life — the `iat` of its file — so the server mark stops
+     * moving, and nothing would notice a clock wound back to the day after
+     * issuance to keep a year-long file alive forever.
+     *
+     * Mixing the two would be worse than useless: a machine whose clock ran fast
+     * would inflate the server mark, and correcting the clock afterwards would
+     * then read as tampering on an install that had done nothing wrong.
+     *
+     * What this bounds is **rollback, not freeze**. A user who stops their clock
+     * keeps a file past its expiry; a user who winds it back is told
+     * `clock_tampered`. That is the honest limit of enforcing a deadline against
+     * a clock its owner controls, and it is the price of offline.
+     */
+    offlineSeen?: number;
 }
 /**
  * Where the binding lives, per product, following each OS's convention.
@@ -982,4 +1158,4 @@ declare function verifyManifest(releaseKeys: Keys, expectedAud: string, token: s
  */
 declare function verifyKeyset(anchorKey: KeyObject, expectedAud: string, token: string): Record<string, unknown>;
 
-export { type AcquireLeaseOptions, type CheckForUpdateOptions, type CheckInOptions, type DeltaOptions, type DownloadProgress, type DownloadProgressCallback, type FetchLike, type FetchResponseLike, type FingerprintData, type Lease, type LicenseListener, LicenseState, StateStore, type StoredBinding, TalosApiError, TalosClient, TalosError, type TalosEventMap, type TalosEventName, type TalosOptions, TalosSignatureError, type UpdateArtifact, type UpdateDelta, type UpdateDeltaTarget, type UpdateInfo, collectFingerprint, defaultStatePath, hashLicenseKey, publicKeyFromBase64, verifyAppliedUpdate, verifyKeyset, verifyManifest, verifyToken };
+export { type AcquireLeaseOptions, type CheckForUpdateOptions, type CheckInOptions, type DeltaOptions, type DownloadProgress, type DownloadProgressCallback, type FetchLike, type FetchResponseLike, type FingerprintData, LICENSE_FILE_KIND, type Lease, type LicenseListener, LicenseState, RECEIPT_DOMAIN, REQUEST_DOMAIN, type SignedDoc, StateStore, type StoredBinding, TalosApiError, TalosClient, TalosError, type TalosEventMap, type TalosEventName, type TalosOptions, TalosSignatureError, type UpdateArtifact, type UpdateDelta, type UpdateDeltaTarget, type UpdateInfo, collectFingerprint, defaultStatePath, hashLicenseKey, publicKeyFromBase64, verifyAppliedUpdate, verifyKeyset, verifyManifest, verifyToken };