@antondziuin/talos-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,985 @@
+import { KeyObject } from 'node:crypto';
+
+/**
+ * What a response has to offer this SDK.
+ *
+ * `headers` and `body` are optional because a test double need not implement a
+ * `ReadableStream`; `arrayBuffer` is not, because the artifact download has to
+ * read bytes and an optional method there just moves the failure to run time —
+ * which is exactly what this shape is being widened to prevent.
+ */
+interface FetchResponseLike {
+    status: number;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    headers?: {
+        get(name: string): string | null;
+    };
+    /** A streaming body, when the implementation has one (the global `fetch`
+     *  does). Used to enforce the size cap without buffering first. */
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(): Promise<unknown>;
+        };
+    } | null;
+}
+/** Minimal fetch signature (Node 18+ global fetch, or an injected one). */
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    /**
+     * Aborts the request once {@link TalosOptions.httpTimeoutMs} elapses.
+     *
+     * Optional so an injected `fetch` that predates this field still satisfies
+     * the type — but one that ignores the signal has no timeout, and the
+     * licensing call it drops is on somebody's launch path.
+     */
+    signal?: AbortSignal;
+}) => Promise<FetchResponseLike>;
+interface TalosOptions {
+    /** The product's public token (`tpt_…`) from the portal. */
+    productToken: string;
+    /**
+     * The product's **anchor** public key, base64 (from the portal's Integration
+     * page). The rotation-safe root: the SDK fetches the anchor-signed keyset and
+     * learns the current license/release keys from it, so rotating a signing key
+     * never breaks a deployed app. Strongly recommended — pin this. If set,
+     * {@link publicKey} is optional (a fallback for when the keyset is unavailable).
+     */
+    anchorPublicKey?: string;
+    /**
+     * The product's Ed25519 license public key, base64. A direct pin used to
+     * verify activation/validation tokens when no keyset is loaded. Optional if
+     * {@link anchorPublicKey} is set.
+     */
+    publicKey?: string;
+    /**
+     * The product's **release**-signing public key, base64. Direct pin used to
+     * verify update manifests when no keyset is loaded. Falls back to
+     * {@link publicKey} when omitted.
+     */
+    releasePublicKey?: string;
+    /** Base URL of the Talos (or self-hosted) server. */
+    serverUrl: string;
+    /** Optional app version reported in telemetry/heartbeats. */
+    appVersion?: string;
+    /**
+     * The name shown for this seat in the developer's portal. Defaults to
+     * `os.hostname()`.
+     *
+     * Unlike the hostname the SDK folds into the fingerprint, this one is stored
+     * and displayed as written — it is what a support agent reads when a customer
+     * says "release the one on my old laptop", and without it every seat on a
+     * licence is an indistinguishable hash prefix. Pass `""` to send nothing if a
+     * machine name would be more identifying than your users expect.
+     */
+    hostname?: string;
+    /**
+     * Optional fetch implementation (defaults to the global `fetch`).
+     *
+     * Used for **every** network call, artifact downloads included. It did not
+     * used to be: `downloadUpdate` reached for `globalThis.fetch` directly, so a
+     * proxy, a custom CA bundle, request logging or a test double applied to
+     * every licensing call and was silently bypassed by the one call that pulls a
+     * multi-megabyte binary and is likeliest to need it.
+     */
+    fetch?: FetchLike;
+    /**
+     * The update channel this install follows (`stable` by default, `beta` and
+     * whatever else the product publishes).
+     *
+     * The default for {@link TalosClient.checkForUpdate}, and the channel a
+     * heartbeat names when something is subscribed to `updateAvailable` — a beta
+     * install has to ask about its own channel or it would be told about
+     * stable's releases.
+     */
+    updateChannel?: string;
+    /**
+     * How long a licensing call may take before it is abandoned, in milliseconds.
+     * Default 10000; `0` disables it.
+     *
+     * Node's `fetch` has **no** default timeout, so before this existed a server
+     * that accepted the connection and never answered left `validate()` pending
+     * forever — which in a desktop application is a splash screen that never goes
+     * away, on the one code path a user cannot skip. Passing a custom `fetch` was
+     * the only way to bound it, which is a lot of ceremony for one number.
+     *
+     * It does **not** apply to `downloadUpdate`. A total-duration cap on a
+     * multi-megabyte artifact is not a safeguard, it is a size limit disguised as
+     * one: the same 30 seconds that is generous for a licensing call fails every
+     * download on a slow connection. The download is bounded by the manifest's
+     * signed `size` instead, which is the bound that actually matters there.
+     */
+    httpTimeoutMs?: number;
+    /**
+     * Extra fingerprint components, merged over the ones the SDK collects.
+     *
+     * Node cannot read hardware identifiers on Windows or macOS without native
+     * modules, so on those hosts the server falls back to exact matching and a
+     * NIC change forces a re-activation. If your app can supply a stable
+     * identifier — an Electron native module, or a value you already hold — pass
+     * it here (e.g. `{ machine_guid: "<value>" }`) and the server can keep the
+     * seat across hardware changes instead. Values are hashed like any other
+     * component, so raw identifiers never leave the machine. See
+     * `docs/FINGERPRINT.md` for the recognised ids and their weights.
+     */
+    fingerprintComponents?: Record<string, string>;
+    /**
+     * Where to keep this machine's activation across restarts. Defaults to a
+     * per-product file under the OS user-data directory (see
+     * {@link defaultStatePath}).
+     */
+    statePath?: string;
+    /**
+     * Persist the machine binding (default `true`).
+     *
+     * Turn it off only for a process that should not leave a licence on disk — a
+     * test, or a short-lived worker. The cost is that every start must
+     * `activate` again, which rotates the activation secret and is refused while
+     * the tenant is suspended, so a long-lived desktop app wants this on.
+     */
+    persistState?: boolean;
+}
+/** One downloadable artifact of an available update (from a verified manifest). */
+interface UpdateArtifact {
+    platform: string;
+    arch: string;
+    kind: string;
+    filename: string;
+    /** Expected size in bytes (from the signed manifest). */
+    size: number;
+    /** Expected SHA-256, lowercase hex (from the signed manifest). */
+    sha256: string;
+    /** Untrusted transport path; the downloaded bytes are verified against `sha256`. */
+    downloadPath?: string;
+}
+/** What applying a patch has to produce. */
+interface UpdateDeltaTarget {
+    /** The `kind` of the full artifact this rebuilds (`installer`, `archive`, …). */
+    kind: string;
+    filename: string;
+    /** Expected size of the rebuilt file, in bytes (from the signed manifest). */
+    size: number;
+    /**
+     * Expected SHA-256 of the rebuilt file, lowercase hex (from the signed
+     * manifest). **Check it after applying** — see {@link verifyAppliedUpdate}.
+     * Verifying only the patch leaves whatever comes out of the patcher
+     * unverified, which is the whole thing the signed manifest exists to prevent.
+     */
+    sha256: string;
+}
+/**
+ * A patch that turns one already-installed version into this release, from the
+ * signed manifest.
+ *
+ * Talos hosts and signs patches; it does not produce or apply them. The diff
+ * format belongs to whatever applies it (Velopack, Squirrel, MSIX, bsdiff,
+ * `zstd --patch-from`), and this SDK deliberately does not run installers.
+ */
+interface UpdateDelta {
+    platform: string;
+    arch: string;
+    /** The installed version this patch applies to, exactly as published. */
+    from: string;
+    /** `release_seq` of the version it applies to (always below this release's). */
+    fromSeq: number;
+    filename: string;
+    /** Expected size of the patch itself, in bytes. */
+    size: number;
+    /** Expected SHA-256 of the patch itself, lowercase hex. */
+    sha256: string;
+    target: UpdateDeltaTarget;
+    /** Untrusted transport path; the bytes are verified against `sha256`. */
+    downloadPath?: string;
+}
+/** A verified available update (its metadata all comes from the signed manifest). */
+interface UpdateInfo {
+    version: string;
+    releaseSeq: number;
+    mandatory: boolean;
+    notesUrl: string | null;
+    artifacts: UpdateArtifact[];
+    /**
+     * Patches this release ships, if any. Never mixed into {@link artifacts}: a
+     * patch is not something a host can install, and an SDK that picks "the
+     * artifact for this platform" would hand one over as if it were a build.
+     */
+    deltas: UpdateDelta[];
+}
+/** Which patch to use, when a release ships more than one. */
+interface DeltaOptions {
+    /**
+     * The version currently installed. Defaults to `appVersion` from the client
+     * options — the same value the update check reports.
+     */
+    from?: string;
+    /**
+     * Which shipped file to rebuild, when a release carries patches for several
+     * (an installer and a portable archive, say). Defaults to the only one, and
+     * is required when there is more than one.
+     */
+    targetKind?: string;
+}
+/**
+ * How far a download has got, passed to the `onProgress` callback of
+ * {@link TalosClient.downloadUpdate} and {@link TalosClient.downloadDelta}.
+ *
+ * `totalBytes` is the size the **signed manifest** names, not the server's
+ * `content-length`. The download host is untrusted, and a bar driven by a header
+ * it controls can be parked at 100% while bytes are still arriving. It is also
+ * the cap the read is bounded by, so `bytesReceived` never exceeds it.
+ */
+interface DownloadProgress {
+    /** Bytes verified and written so far. */
+    bytesReceived: number;
+    /** Total size, in bytes, from the signed manifest. */
+    totalBytes: number;
+}
+/** Called as an artifact download advances. */
+type DownloadProgressCallback = (progress: DownloadProgress) => void;
+/**
+ * The licence transitions a host can subscribe to with {@link TalosClient.on}.
+ *
+ * Edges, not levels. `onState` already delivers the verdict on every check-in,
+ * and an application that wants "tell me when grace starts" has to diff those
+ * itself — getting that right (not re-warning every ten minutes for the whole
+ * outage) is exactly the bookkeeping a library should do once instead of every
+ * host doing it slightly wrong.
+ */
+interface TalosEventMap {
+    /** The licence stopped being usable; the payload says why. */
+    licenseInvalid: LicenseState;
+    /** Running on a cached verdict because the server could not be reached. */
+    gracePeriodStarted: LicenseState;
+    /** The offline window closed: the cached verdict may no longer be honoured. */
+    gracePeriodExpired: LicenseState;
+    /** The system clock moved back behind a signed server time already seen. */
+    clockTamperDetected: LicenseState;
+    /**
+     * A release newer than this install is waiting, noticed by a heartbeat rather
+     * than by being asked. The payload is the same verified {@link UpdateInfo}
+     * {@link TalosClient.checkForUpdate} returns.
+     */
+    updateAvailable: UpdateInfo;
+}
+type TalosEventName = keyof TalosEventMap;
+/** Handler for a licence transition; receives the state that was adopted. */
+type LicenseListener = (state: LicenseState) => void;
+/** A held floating seat. Renew before {@link expiresAt} or it is reclaimed. */
+interface Lease {
+    /** Server-side lease id (from the signed token). */
+    id: string;
+    /** This process's instance id. */
+    instanceId: string;
+    /** Unix seconds when the seat is reclaimed unless renewed. */
+    expiresAt: number;
+    /** Renew after this many seconds (server-chosen, ttl/3). */
+    renewAfterSeconds: number;
+    seatsInUse: number;
+    maxSeats: number;
+}
+interface AcquireLeaseOptions {
+    /**
+     * Identifies this running process. Re-acquiring with the same value renews
+     * instead of taking a second seat. Defaults to a random per-client id.
+     */
+    instanceId?: string;
+    /** Auto-renew in the background (default true). Call {@link TalosClient.releaseLease} to stop. */
+    autoRenew?: boolean;
+    /** Called if a renewal fails and the seat is lost (e.g. revoked, server down). */
+    onLeaseLost?: (reason: string) => void;
+}
+interface CheckInOptions {
+    /** Called after every successful check-in, with the fresh verdict. */
+    onState?: (state: LicenseState) => void;
+    /**
+     * Called when a check-in fails outright — the server answered with an error,
+     * or the network is down *and* there is nothing left to fall back on.
+     */
+    onError?: (error: unknown) => void;
+}
+interface CheckForUpdateOptions {
+    /** Currently installed version (informational). */
+    currentVersion?: string;
+    /**
+     * Override the anti-downgrade floor for this call.
+     *
+     * Optional, and normally omitted: the SDK persists the highest `release_seq`
+     * it has seen this install running and uses that. Pass one when the host
+     * knows something the SDK cannot — a build installed by a package manager, or
+     * a first run after adopting the SDK on an already-updated fleet.
+     */
+    currentReleaseSeq?: number;
+    /** Update channel; defaults to `stable`. */
+    channel?: string;
+}
+/** The current, cryptographically-verified license verdict. */
+declare class LicenseState {
+    /**
+     * `valid | expired | revoked | suspended | deactivated | machine_revoked |
+     * invalid`, plus two verdicts only the client can reach:
+     * `grace_expired` (offline past the licence's grace window) and
+     * `clock_tampered` (the system clock moved back behind a signed server
+     * time we had already seen).
+     */
+    readonly decision: string;
+    /** Entitlement bag (server-defined). */
+    readonly features: Record<string, unknown>;
+    /** Business expiry (unix seconds), or null for perpetual. */
+    readonly licenseExpiresAt: number | null;
+    /**
+     * True when this verdict came from the local cache rather than a live
+     * server — the licence is being honoured on trust, inside the window the
+     * policy allows.
+     */
+    readonly isOffline: boolean;
+    /**
+     * Unix seconds after which the app should validate again. Chosen by the
+     * server and carried in a signed claim, so it cannot be lengthened in
+     * transit.
+     */
+    readonly revalidateAfter: number | null;
+    /** Unix seconds until which this verdict may be honoured offline. */
+    readonly graceUntil: number | null;
+    constructor(
+    /**
+     * `valid | expired | revoked | suspended | deactivated | machine_revoked |
+     * invalid`, plus two verdicts only the client can reach:
+     * `grace_expired` (offline past the licence's grace window) and
+     * `clock_tampered` (the system clock moved back behind a signed server
+     * time we had already seen).
+     */
+    decision: string, 
+    /** Entitlement bag (server-defined). */
+    features: Record<string, unknown>, 
+    /** Business expiry (unix seconds), or null for perpetual. */
+    licenseExpiresAt: number | null, 
+    /**
+     * True when this verdict came from the local cache rather than a live
+     * server — the licence is being honoured on trust, inside the window the
+     * policy allows.
+     */
+    isOffline?: boolean, 
+    /**
+     * Unix seconds after which the app should validate again. Chosen by the
+     * server and carried in a signed claim, so it cannot be lengthened in
+     * transit.
+     */
+    revalidateAfter?: number | null, 
+    /** Unix seconds until which this verdict may be honoured offline. */
+    graceUntil?: number | null);
+    get isValid(): boolean;
+    isFeatureEnabled(name: string): boolean;
+    getEntitlement(name: string): unknown;
+}
+declare class TalosClient {
+    private readonly options;
+    private readonly anchorKey;
+    private readonly publicKey;
+    private readonly releaseKey;
+    private readonly fingerprint;
+    private readonly fp;
+    private readonly doFetch;
+    private keysetLicenseKeys;
+    private 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`.
+     */
+    private licenseKeyHash;
+    private activationSecret;
+    private machineId;
+    private readonly store;
+    /** Everything persisted for this product; written back as one file. */
+    private binding;
+    /**
+     * 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.
+     */
+    private keysetFromCache;
+    /**
+     * 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.
+     */
+    private keysetIssuedAt;
+    /** The policy's heartbeat cadence, from the last heartbeat's signed claims. */
+    private heartbeatInterval;
+    private checkInTimer;
+    /** Bumped on stop so an in-flight tick cannot re-arm a cancelled loop. */
+    private checkInGeneration;
+    private lease;
+    private renewTimer;
+    /** Bumped on release so an in-flight renewal cannot resurrect the seat. */
+    private leaseGeneration;
+    /** Default instance id for floating leases: one per client object. */
+    private readonly instanceId;
+    current: LicenseState | null;
+    private readonly listeners;
+    /** The newest release this client has already announced. */
+    private announcedReleaseSeq;
+    constructor(options: TalosOptions);
+    /**
+     * 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.
+     */
+    private promoteDownloadedRelease;
+    /**
+     * 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.
+     */
+    private releaseFloor;
+    /**
+     * 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(): boolean;
+    /** The server's id for this machine, once activated. */
+    get currentMachineId(): string | null;
+    isFeatureEnabled(name: string): boolean;
+    /**
+     * 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.
+     */
+    refreshKeyset(): Promise<void>;
+    /**
+     * 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.
+     */
+    private ensureKeyset;
+    /**
+     * 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.
+     */
+    private keysetIsStale;
+    /** Verify a keyset token against the anchor and adopt its keys. */
+    private adoptKeyset;
+    /** Keys to verify license tokens with: the keyset if loaded, else the direct pin. */
+    private licenseVerifyKeys;
+    /** Keys to verify manifests with: the keyset if loaded, else the direct pin. */
+    private releaseVerifyKeys;
+    /**
+     * 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.
+     */
+    activate(licenseKey: string): Promise<LicenseState>;
+    /**
+     * 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(): number | null;
+    /**
+     * 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<E extends TalosEventName>(event: E, listener: (payload: TalosEventMap[E]) => void): () => void;
+    /**
+     * 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.
+     */
+    private adopt;
+    private emit;
+    /**
+     * 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?: CheckInOptions): void;
+    /** Stop the background check-ins started by {@link startCheckIns}. */
+    stopCheckIns(): void;
+    /** Drop the machine binding, in memory and on disk. */
+    private forgetBinding;
+    /** Merge fields into the persisted binding and write it back. */
+    private persist;
+    /**
+     * 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.
+     */
+    private advanceClock;
+    validate(): Promise<LicenseState>;
+    /**
+     * 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.
+     */
+    private offlineDecision;
+    deactivate(): Promise<void>;
+    /**
+     * 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.
+     */
+    private reportedHostname;
+    heartbeat(): Promise<LicenseState>;
+    /** The channel this install follows; `stable` unless set. */
+    private updateChannel;
+    /**
+     * 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.
+     */
+    private announceUpdate;
+    /**
+     * 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.
+     */
+    acquireLease(opts?: AcquireLeaseOptions): Promise<Lease>;
+    /** Best-effort DELETE of one instance's seat (used for stale-renewal cleanup). */
+    private releaseInstance;
+    /** The currently held floating seat, if any. */
+    get currentLease(): Lease | null;
+    /** Release the floating seat (clean exit) and stop auto-renewal. */
+    releaseLease(): Promise<void>;
+    private scheduleRenew;
+    private stopRenew;
+    /**
+     * 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.
+     */
+    checkForUpdate(opts?: CheckForUpdateOptions): Promise<UpdateInfo | null>;
+    /**
+     * 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: UpdateInfo, opts?: DeltaOptions): UpdateDelta | 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.
+     */
+    downloadDelta(info: UpdateInfo, destPath: string, opts?: DeltaOptions & {
+        delta?: UpdateDelta;
+        onProgress?: DownloadProgressCallback;
+    }): Promise<UpdateDelta>;
+    /**
+     * 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}.
+     */
+    downloadUpdate(info: UpdateInfo, destPath: string, artifact?: UpdateArtifact, onProgress?: DownloadProgressCallback): Promise<UpdateArtifact>;
+    /**
+     * 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.
+     */
+    private rememberDownloaded;
+    /**
+     * 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.
+     */
+    private fetchVerified;
+    private requireActivated;
+    private post;
+    /**
+     * 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.
+     */
+    private timeoutSignal;
+    private request;
+}
+/**
+ * Check that applying a patch produced the file the signed manifest said it
+ * would. Throws {@link TalosSignatureError} if not.
+ *
+ * This is the last link in the chain and the easiest one to leave out. The patch
+ * itself was verified on the way in, but a patcher can fail halfway, apply to
+ * the wrong base file, or be handed bytes from somewhere else entirely — and
+ * every one of those produces a file that nothing has vouched for. Reads the
+ * file in chunks, so a multi-gigabyte install is not brought into memory.
+ *
+ * Needs no licence and no activation: run it from the updater process, after the
+ * application it belongs to has exited.
+ */
+declare function verifyAppliedUpdate(filePath: string, delta: UpdateDelta): Promise<void>;
+
+/** Base class for all Talos SDK errors. */
+declare class TalosError extends Error {
+    constructor(message: string);
+}
+/**
+ * A server response failed cryptographic verification against the pinned
+ * product key (bad signature, wrong nonce/audience/type, or expired). Treated
+ * like a network failure — never as "valid".
+ */
+declare class TalosSignatureError extends TalosError {
+    constructor(message: string);
+}
+/** A non-success HTTP response from the Talos runtime API. */
+declare class TalosApiError extends TalosError {
+    readonly statusCode: number;
+    readonly errorCode: string | undefined;
+    constructor(statusCode: number, errorCode: string | undefined);
+}
+
+/** A machine fingerprint: the composite plus the per-component hashes. */
+interface FingerprintData {
+    /** What the server matches on. Derived from {@link components}. */
+    composite: string;
+    /** `{component_id: hash}` — lets the server tolerate hardware drift. */
+    components: Record<string, string>;
+}
+/**
+ * Collect a machine fingerprint.
+ *
+ * Each component is HMAC'd with a product-scoped key before it leaves the
+ * machine, so the server stores hashes and never the underlying identifiers,
+ * and the same hardware yields different hashes for different products.
+ *
+ * **Coverage is thin here, and honestly so.** Node has no hardware access
+ * without native modules, and this SDK ships with zero dependencies and never
+ * spawns a subprocess. On Linux it can read `/etc/machine-id`, which is enough
+ * for the server to recognise a machine across a hardware change. On Windows and
+ * macOS it cannot reach anything comparable, so those hosts stay on exact
+ * matching: change a NIC and the user re-activates. If your app can do better —
+ * Electron with a native module, or a value you already have — pass
+ * `fingerprintComponents` in the options and the server will use it. See
+ * `docs/FINGERPRINT.md` for the recognised ids and their weights.
+ *
+ * None of this resists a determined attacker: these values are produced on the
+ * client and can be forged. They exist to recognise honest hardware churn.
+ */
+declare function collectFingerprint(productToken: string, extra?: Record<string, string>): FingerprintData;
+
+/**
+ * The machine binding the server hands back at activation, held across process
+ * restarts.
+ *
+ * Without this the binding died with the process and every application start
+ * had to call `activate` again — which burns a round trip the protocol was
+ * designed to avoid, rotates the activation secret out from under any other
+ * running copy, and (because `activate` is the one client route refused for a
+ * suspended tenant) turns the platform owner's deliberately graduated
+ * suspension into a hard kill switch for the developer's own paying users.
+ */
+interface StoredBinding {
+    /**
+     * SHA-256 of the licence key as it was typed, hex — **not** the key.
+     *
+     * The key itself used to live here, so that the next call could send it. It
+     * no longer has to: the server resolves a licence from the activation secret,
+     * which is the credential these calls authenticate with anyway. What was left
+     * was a plaintext licence key in a file on every customer's machine, which is
+     * a credential-shaped file and exactly what an infostealer collects.
+     *
+     * A hash is kept because one thing still needs it: `activate()` called twice
+     * with the same key must validate rather than spend a second seat, and that
+     * comparison is all the stored value was ever used for. The hash cannot be
+     * replayed to the server — the server matches an HMAC under its own pepper —
+     * so this is a value with exactly one use and no resale.
+     *
+     * Hashed as typed, without normalising, because the comparison it replaces
+     * was a string equality on the same input: normalising here would change when
+     * a re-activation is avoided, which is not what this change is about.
+     */
+    licenseKeyHash: string;
+    activationSecret: string;
+    machineId: string;
+    /**
+     * The fingerprint composite at activation time. Informational: it is *not*
+     * required to match on restore, because a machine whose hardware drifted is
+     * exactly the case the server's fuzzy matcher exists to resolve. Discarding
+     * the binding here would re-activate the customer whose disk was replaced —
+     * the support ticket the drift budget was built to prevent.
+     */
+    fingerprint: string;
+    /**
+     * The last anchor-signed keyset token.
+     *
+     * Cached because an anchor-only client — the pinning that survives key
+     * rotation — otherwise has no verification key at all until it can reach the
+     * server, which is exactly the situation the offline path exists for. The
+     * anchor is compiled into the app, the keyset is signed by it, and the
+     * validation token is signed by a key it lists: the whole chain verifies
+     * offline against a root the network cannot influence.
+     */
+    keyset?: string;
+    /** The last verified `typ=validation` token — the offline verdict. */
+    validation?: string;
+    /**
+     * The highest server clock ever seen, in unix seconds, taken from a signed
+     * claim.
+     *
+     * This is what makes offline grace bounded. Grace is evaluated against the
+     * local clock, which the user controls; with no mark that only moves forward,
+     * winding the clock back would renew a 72-hour window indefinitely. A
+     * monotonic timer is not a substitute — it resets on reboot and on a VM
+     * snapshot restore, which is the case that matters.
+     */
+    timeHighWater?: number;
+    /**
+     * The highest `release_seq` this install is known to be running, and the
+     * floor `checkForUpdate` refuses to go below.
+     *
+     * Anti-downgrade only works against a mark that outlives the process, and
+     * until this existed there was none: the floor came entirely from
+     * `currentReleaseSeq`, which the host had to compute and pass, and which no
+     * example passed. `docs/SECURITY.md` described a high-water mark that did not
+     * exist, so "yanking a release does not recall it from installs that already
+     * applied it" rested on the host having implemented the mark itself.
+     */
+    releaseSeqHighWater?: number;
+    /**
+     * A release whose bytes were downloaded and verified but which is not
+     * running yet: the version string from its signed manifest, and its
+     * `release_seq`.
+     *
+     * The SDK downloads; the host installs, in its own way, on its own schedule,
+     * usually after a restart. So "installed" is not an event the SDK can see —
+     * but the *result* is, because the host tells it which version it is on every
+     * time a client is constructed. When `appVersion` matches what was downloaded,
+     * the download became an install and the mark advances.
+     *
+     * The alternative was a `markInstalled()` for the host to call, and the whole
+     * defect here is a mark that depended on the host doing something nobody
+     * documented and no example did.
+     */
+    pendingRelease?: {
+        version: string;
+        releaseSeq: number;
+    };
+}
+/**
+ * Where the binding lives, per product, following each OS's convention.
+ *
+ * The directory is named by a hash of the product token rather than the token
+ * itself: it keeps the path filesystem-safe without assuming anything about the
+ * token's alphabet, and two products never collide.
+ */
+declare function defaultStatePath(productToken: string): string;
+/**
+ * SHA-256 of a licence key, hex.
+ *
+ * Used only to recognise "the same key as last time" without keeping the key.
+ * Not a credential and not accepted by anything: the server matches an HMAC
+ * computed under a pepper this process has never seen.
+ */
+declare function hashLicenseKey(key: string): string;
+/** Reads and writes one product's machine binding. */
+declare class StateStore {
+    readonly path: string;
+    private readonly productToken;
+    private readonly key;
+    constructor(path: string, productToken: string, keyMaterial: string);
+    /**
+     * 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(): StoredBinding | 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: StoredBinding): boolean;
+    /** Forget the binding (deactivation). */
+    clear(): void;
+}
+
+/** Wrap a base64-encoded raw 32-byte Ed25519 public key as a KeyObject. */
+declare function publicKeyFromBase64(b64: string): KeyObject;
+type Keys = KeyObject | KeyObject[];
+/**
+ * Verify a Talos-compact token
+ * (`talos.<ver>.<typ>.<b64url(payload)>.<b64url(sig)>`, Ed25519 over the exact
+ * ASCII prefix). `keys` may be a single pinned key or a keyset (any of which may
+ * have signed it). IGNORES any `kid` and enforces `typ`, `aud`, the echoed
+ * nonce, and `nbf`/`exp`.
+ */
+declare function verifyToken(keys: Keys, expectedTyp: string, expectedAud: string, expectedNonce: string, token: string): Record<string, unknown>;
+/**
+ * Verify a signed update **manifest** (`typ=manifest`) against the pinned
+ * release key(s). Unlike per-request tokens a manifest is a long-lived, static
+ * artifact, so there is no nonce and no short `exp`; instead it carries a
+ * `not_before` gate. Enforces scheme/version/`typ`, the signature, `aud`, and
+ * `not_before`.
+ */
+declare function verifyManifest(releaseKeys: Keys, expectedAud: string, token: string): Record<string, unknown>;
+/**
+ * Verify a signed **keyset** (`typ=keyset`) against the pinned anchor key. The
+ * keyset lists the product's current, rotatable license/release public keys, so
+ * an SDK that pins only the anchor learns the signing keys from it — a rotated
+ * key never breaks a deployed app. Enforces scheme/version/`typ`, the anchor
+ * signature, and `aud`.
+ */
+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 };