@moonbase.sh/licensing 2.0.1 → 3.1.0

package/dist/index.d.ts

@@ -1,10 +1,329 @@
+import { Buffer } from 'node:buffer';
 import { z } from 'zod';
 
+/**
+ * Reference implementation of the Moonbase device fingerprint spec (v2). The
+ * authoritative, language-neutral definition lives in FINGERPRINT_SPEC.md, and
+ * the machine-readable conformance suite in fingerprint-vectors.json. Any SDK
+ * that conforms computes the same id on a given machine. Keep all three in
+ * lockstep; when they disagree, the vectors decide.
+ *
+ * A device id is a stamped SHA-256 of a deterministic "material" string built
+ * from stable native hardware identifiers:
+ *
+ *   mbd2_<lowercase-hex sha256 of the material>
+ *
+ * Material layout (lines joined with "\n", NO trailing newline):
+ *
+ *   moonbase:fingerprint:v2
+ *   platform=<tag>
+ *   <name>=<value>
+ *   ...
+ *
+ * Every value is canonicalized (NFC, non-printable-ASCII dropped, capped,
+ * space-trimmed); empty values are skipped; duplicate parameter names are
+ * rejected; and a material that does not identify the individual machine — no
+ * parameters at all, or only model-level ones — is an error rather than a digest,
+ * so a machine or a whole product line can never share one id.
+ */
+declare const FINGERPRINT_PREFIX = "moonbase:fingerprint:v2";
+/** Spec version. Always equal to the digit in {@link FINGERPRINT_PREFIX} and in the stamp. */
+declare const FINGERPRINT_VERSION = 2;
+/** Longest permitted canonical value, in characters. */
+declare const MAX_VALUE_LENGTH = 128;
+/**
+ * What the material was built from. `identity` is the real hardware fingerprint;
+ * `deviceName` is the opt-in, deliberately weaker host-name fallback; `scoped` is
+ * an id that is stable only within one app scope (iOS/Android, where the platform
+ * exposes nothing an unrelated app can read). Each is stamped distinctly so a
+ * server can tell them apart.
+ */
+type DeviceIdSource = 'identity' | 'deviceName' | 'scoped';
+/** The tags this version defines, as a detached frozen map (see {@link IDENTIFYING_PARAM_NAMES}). */
+declare const DEVICE_ID_SOURCE_TAGS: Readonly<Record<DeviceIdSource, string>>;
+type PlatformTag = 'mac' | 'ios' | 'windows' | 'android' | 'linux' | 'bsd' | 'unknown';
+/**
+ * The source a successful identity read earns on this platform.
+ *
+ * Scoped platforms expose no identifier an unrelated app can read, so anything
+ * built from their parameters is scoped to the app and must be stamped `mbd2s_`.
+ * Stamping it `mbd2_` would tell a server the id is a hardware fingerprint
+ * comparable across every app on the device, which is exactly what it is not:
+ * the server would then be entitled to correlate ids the spec forbids
+ * correlating, and a diagnostic would offer remedies that cannot apply.
+ *
+ * Derived from the platform rather than chosen by the caller, so a host that
+ * bridges `identifierForVendor` or `androidId` through a custom
+ * {@link DeviceIdentityReader} cannot accidentally mislabel it.
+ */
+declare function identitySource(platform: PlatformTag): DeviceIdSource;
+type FingerprintParam = readonly [name: string, value: string];
+interface DeviceIdentity {
+    /** Ordered identity params. Empty values are dropped by the material builder. */
+    params: FingerprintParam[];
+    /** Human-readable device name. Never part of the default material. */
+    deviceName: string;
+}
+/** Reads raw device identity for the current platform. Injectable for testing. */
+interface DeviceIdentityReader {
+    read: () => DeviceIdentity;
+}
+/** A device id stamp broken into its parts (see {@link parseDeviceIdStamp}). */
+interface DeviceIdStamp {
+    /** Fingerprint spec version that produced the digest. */
+    version: number;
+    /** The literal source tag: `''`, `'n'`, `'s'`, or one a newer SDK introduced. */
+    sourceTag: string;
+    /** What {@link sourceTag} means, or `null` when this SDK does not define that tag. */
+    source: DeviceIdSource | null;
+    /** The 64-char lowercase-hex SHA-256. */
+    digest: string;
+}
+/**
+ * Canonicalize a raw value read from the system (see FINGERPRINT_SPEC.md,
+ * "Canonicalizing values"): NFC-normalize, drop every character outside
+ * printable ASCII, cap the length, then trim spaces from both ends.
+ *
+ * Dropping non-printables is what makes the algorithm implementable
+ * byte-identically in any language: it removes the newline-injection ambiguity
+ * from the material grammar, and it makes the decoding choice for raw firmware
+ * strings (latin1 vs. UTF-8 vs. raw bytes) immaterial, since every byte those
+ * decodings disagree about is discarded either way.
+ */
+declare function canonicalizeValue(value: string): string;
+/**
+ * Map a Node.js `process.platform` value onto a canonical platform tag, or pass
+ * through a value that is already one.
+ *
+ * The passthrough is what makes the mobile platforms reachable at all. Node does
+ * not run on iOS, so `process.platform` is never `'ios'` and no amount of mapping
+ * can produce that tag — yet a host embedding Node can bridge
+ * `identifierForVendor` from platform API. Without this, such a host has no way
+ * to say which platform it is on: the value would fall through to `'unknown'`,
+ * and the material would carry `platform=unknown`, so the digest would not match
+ * what a conforming iOS SDK computes on the same device, and the id would be
+ * stamped `mbd2_` rather than `mbd2s_`. Both wrong, and both silent.
+ *
+ * `'android'` and `'linux'` belong to both vocabularies and map to themselves, so
+ * the two spellings cannot disagree.
+ */
+declare function platformTag(platform?: NodeJS.Platform | PlatformTag): PlatformTag;
+/**
+ * The identifying parameter names, as a detached frozen list.
+ *
+ * Deliberately not the `Set` this module checks against. `ReadonlySet` is erased
+ * at compile time, so exporting the live set would let any JavaScript consumer —
+ * or any dependency — call `.add('sysVendor')` and turn model-level values into
+ * accepted identity for the whole process, silently undoing the collision
+ * protection below.
+ */
+declare const IDENTIFYING_PARAM_NAMES: readonly string[];
+/**
+ * Canonicalize every value and drop the ones that end up empty, plus any
+ * identifying parameter holding an unprogrammed placeholder. Order is preserved.
+ * Exported so a caller can see which parameters actually contributed without
+ * rebuilding the material.
+ *
+ * @throws when two surviving parameters share a name — the material grammar has
+ * no way to express that, so it is a collection bug rather than a machine state.
+ */
+declare function canonicalizeParams(params: ReadonlyArray<FingerprintParam>): FingerprintParam[];
+/**
+ * Assemble the canonical fingerprint material string. Pure and deterministic —
+ * exported so consumers can verify cross-SDK parity against the shipped vectors.
+ *
+ * @throws {InsufficientDeviceIdentityError} when no parameter survives canonicalization, or when
+ * none of the survivors identifies the individual machine.
+ */
+declare function buildFingerprintMaterial(platform: PlatformTag, params: ReadonlyArray<FingerprintParam>): string;
+/** Hash fingerprint material into a bare digest: 64-char lowercase hex SHA-256. */
+declare function fingerprintDigest(material: string): string;
+/** Prefix a digest with its version and source, producing the wire-form device id. */
+declare function stampDeviceId(digest: string, source?: DeviceIdSource): string;
+/** Hash material and stamp it: the full device id as sent to Moonbase and stored in `sig`. */
+declare function fingerprintDeviceId(material: string, source?: DeviceIdSource): string;
+/**
+ * Split a stamped device id into its parts, or `null` if it is not a Moonbase
+ * stamp at all (a legacy id, or one from a custom resolver). Lets a validator tell
+ * "this license belongs to another machine" apart from "this license was bound
+ * by an older fingerprint version".
+ *
+ * An id whose *tag* is unrecognised still parses, with `source` null: it came from
+ * a newer SDK, and reporting it as unparseable would be worse than saying so.
+ */
+declare function parseDeviceIdStamp(deviceId: string): DeviceIdStamp | null;
+/** Extract `IOPlatformUUID` from `ioreg` output: hyphens stripped, uppercased (spec: macOS `ioPlatformUuid`). */
+declare function parseIoregPlatformUuid(ioregOutput: string): string;
+/**
+ * Pick the first source holding a real machine id, or `''`.
+ *
+ * Each candidate is *validated*, not merely checked for being non-empty:
+ * `machine-id(5)` defines the file as exactly 32 lowercase hex digits, and
+ * legitimately holds the literal marker `uninitialized` in an initrd or a golden
+ * image awaiting first boot. Every machine deployed from such an image reads that
+ * same marker, so accepting it would hand them all one device id — and would also
+ * stop the fall-through to a D-Bus id that may be perfectly valid.
+ */
+declare function selectMachineId(...sources: string[]): string;
+/**
+ * Extract the ordered identity params from a raw SMBIOS structure table: the
+ * **first** type-1 (System) and **first** type-2 (Baseboard) structures only.
+ *
+ * Type 4 (Processor) is deliberately not collected — its values are model-class
+ * rather than per-machine, and the number of type-4 structures tracks the CPU
+ * socket / vCPU count, so collecting them would change the device id whenever a
+ * VM is resized.
+ */
+declare function parseSmbiosParams(smbiosData: Buffer): FingerprintParam[];
+/** The real, platform-dispatching identity reader used by {@link MoonbaseDeviceIdResolver}. */
+declare function defaultDeviceIdentityReader(platform?: NodeJS.Platform | PlatformTag): DeviceIdentityReader;
+
 interface IDeviceIdResolver {
+    resolveDeviceName: () => Promise<string>;
+    resolveDeviceId: () => Promise<string>;
+}
+/**
+ * A device id plus the provenance needed to reason about it — safe to log, show
+ * in an about box, or attach to a support ticket.
+ *
+ * Parameter *names* only, deliberately. Their values are hardware serial numbers,
+ * and a hash of one is no safer to publish: an unsalted digest is a stable global
+ * correlator for the machine, and low-entropy values like host names or
+ * sequential serials fall to a dictionary. `machine-id(5)` is explicit that the
+ * Linux machine id is confidential and must only ever be exposed through an
+ * application-specific *keyed* hash. Which parameters contributed is the useful
+ * diagnostic anyway; what they read is not.
+ */
+interface DeviceIdDescription {
+    deviceId: string;
+    /** Fingerprint spec version that produced it. */
+    version: number;
+    platform: PlatformTag;
+    source: DeviceIdSource;
+    /** Names of the identity parameters that went into the material, in order. */
+    paramNames: string[];
+}
+/** A resolver that can explain how it arrived at its device id. */
+interface IDescribableDeviceIdResolver extends IDeviceIdResolver {
+    describeDevice: () => Promise<DeviceIdDescription>;
+}
+/**
+ * A resolver that also recognises device ids this machine used to have.
+ *
+ * Deliberately separate from {@link IDeviceIdResolver.resolveDeviceId}, which
+ * stays single-valued: what a device binds on activation and what a validator
+ * accepts are different questions, and conflating them is what forces the
+ * all-or-nothing migration choice.
+ */
+interface IMigratingDeviceIdResolver extends IDeviceIdResolver {
+    acceptsDeviceId: (deviceId: string) => Promise<boolean>;
+}
+interface MoonbaseDeviceIdResolverOptions {
+    /** Overrides the identity source. Primarily for testing. */
+    reader?: DeviceIdentityReader;
+    /**
+     * Overrides the detected platform. Accepts a Node.js `process.platform` value
+     * or a canonical {@link PlatformTag}.
+     *
+     * The tag spelling exists for hosts that bridge a platform Node does not run
+     * on: pass `'ios'` together with a {@link reader} that supplies
+     * `identifierForVendor`. Without it the platform would resolve to `'unknown'`,
+     * which changes the material and so the device id.
+     */
+    platform?: NodeJS.Platform | PlatformTag;
+    /**
+     * What to do when no hardware identity is readable. `'none'` (the default)
+     * throws {@link InsufficientDeviceIdentityError}; `'deviceName'` falls back to
+     * hashing the host name, producing a deliberately weaker id stamped `mbd2n_`.
+     *
+     * The fallback is opt-in because a host name is user-renameable, frequently
+     * duplicated across imaged machines, and regenerated on every container start.
+     *
+     * It is **ignored on iOS and Android**, which throw regardless: there the host
+     * name is identical on every device, so the fallback would give a whole install
+     * base one id rather than merely a weak one.
+     */
+    fallback?: 'none' | 'deviceName';
+}
+/**
+ * Default resolver. Implements the Moonbase device fingerprint spec (v2; see
+ * FINGERPRINT_SPEC.md), building the `moonbase:fingerprint:v2` material from
+ * native hardware identifiers (SMBIOS on Windows, `IOPlatformUUID` on macOS,
+ * `machine-id` + DMI on Linux) and stamping its SHA-256 as `mbd2_<hex>`. Every
+ * Moonbase SDK that implements the spec produces the same id on a given machine.
+ *
+ * The result is memoized: reading identity can mean spawning a subprocess, and
+ * both activation and every validation ask for it.
+ */
+declare class MoonbaseDeviceIdResolver implements IDescribableDeviceIdResolver {
+    private readonly reader;
+    private readonly platform;
+    private readonly fallback;
+    private identity?;
+    private described?;
+    constructor(options?: MoonbaseDeviceIdResolverOptions);
+    resolveDeviceName(): Promise<string>;
+    resolveDeviceId(): Promise<string>;
+    /**
+     * A fresh copy each call. The device binding is what activation sends and what
+     * validation compares, so handing out the resolver's own object would let a
+     * consumer that edits a diagnostic — or logs it through something that
+     * normalizes in place — silently change the id every later call returns.
+     */
+    describeDevice(): Promise<DeviceIdDescription>;
+    private compute;
+    /**
+     * Read identity at most once. Both halves of an activation request ask for it —
+     * the name and then the id — and a read can mean spawning `ioreg` or
+     * PowerShell, so reading per call would double the cost of every request and
+     * let the name and the id come from two different reads of the machine.
+     */
+    private readIdentity;
+    private computeDescription;
+    private describe;
+}
+/**
+ * Binds the current fingerprint but keeps recognising ids this device was bound
+ * to before — the migration path off an older algorithm without a flag day.
+ *
+ * `resolveDeviceId` always returns the *current* resolver's id, so every new
+ * activation binds the current algorithm; the historical resolvers are consulted
+ * only when a validator is deciding whether to accept an already-issued license.
+ * A fleet therefore migrates as licenses are naturally re-activated, instead of
+ * every device re-activating at once — which would burn a second activation seat
+ * per device and reset device-scoped trials.
+ *
+ * ```ts
+ * new MigratingDeviceIdResolver(new MoonbaseDeviceIdResolver(), new LegacyDeviceIdResolver())
+ * ```
+ *
+ * Historical ids are computed lazily — only on a mismatch — and then memoized,
+ * so the cost is never paid on the happy path. A historical resolver that throws
+ * is simply skipped.
+ *
+ * Every accepted id is recomputed from the machine's own hardware on each call.
+ * Nothing is read from disk, so widening what a validator accepts does not widen
+ * what an attacker can assert.
+ */
+declare class MigratingDeviceIdResolver implements IMigratingDeviceIdResolver {
+    private readonly current;
+    private readonly previous;
+    private previousIds?;
+    /** Forwarded so the current resolver stays describable through this wrapper. */
+    describeDevice?: () => Promise<DeviceIdDescription>;
+    constructor(current: IDeviceIdResolver, ...previous: IDeviceIdResolver[]);
     resolveDeviceName(): Promise<string>;
     resolveDeviceId(): Promise<string>;
+    acceptsDeviceId(deviceId: string): Promise<boolean>;
 }
-declare class DefaultDeviceIdResolver implements IDeviceIdResolver {
+/**
+ * @deprecated The previous default resolver. Its device id is a base64 SHA-256 of
+ * normalized `systeminformation` fields and does **not** implement the
+ * `moonbase:fingerprint:v2` spec (FINGERPRINT_SPEC.md). Kept so deployments can keep
+ * validating licenses that were bound under the old id during migration; prefer
+ * {@link MoonbaseDeviceIdResolver}.
+ */
+declare class LegacyDeviceIdResolver implements IDeviceIdResolver {
     resolveDeviceName(): Promise<string>;
     resolveDeviceId(): Promise<string>;
 }
@@ -175,7 +494,7 @@ interface ILicenseClient {
      *
      * @returns Details about the requested activation with url to open in the browser
      */
-    requestActivation(): Promise<ActivationRequestResponse>;
+    requestActivation: () => Promise<ActivationRequestResponse>;
     /**
      * Takes in a activation request created through {@link requestActivation}
      * and checks if the request has been fulfilled yet.
@@ -185,7 +504,7 @@ interface ILicenseClient {
      * @param request The activation request to poll
      * @returns A license if the request has been fulfilled, else null
      */
-    getRequestedActivation(request: ActivationRequestResponse): Promise<License | null>;
+    getRequestedActivation: (request: ActivationRequestResponse) => Promise<License | null>;
     /**
      * Requests a trial license for the product.
      * This can only be done once per product per device, and skips
@@ -194,7 +513,7 @@ interface ILicenseClient {
      *
      * @returns The allocated trial license, throws if the trial license cannot be allocated (e.g. user already had a trial) or if the request failed
      */
-    requestTrial(): Promise<License>;
+    requestTrial: () => Promise<License>;
     /**
      * Checks if the given license is still valid, not revoked
      * and returns an updated license if still active.
@@ -205,7 +524,7 @@ interface ILicenseClient {
      * @param license The license to validate
      * @returns An updated license
      */
-    validateLicense(license: License): Promise<License>;
+    validateLicense: (license: License) => Promise<License>;
     /**
      * Contrary to {@linkvalidateLicense }, this method takes
      * in raw bytes of the license, which can be useful if you're
@@ -214,14 +533,14 @@ interface ILicenseClient {
      * @param license The license to validate
      * @returns An updated license
      */
-    validateRawLicense(rawLicense: Buffer): Promise<License>;
+    validateRawLicense: (rawLicense: Buffer) => Promise<License>;
     /**
      * Given a license, this method will try to revoke the license activation,
      * freeing up a seat for other devices to activate the license.
      * This will not work for offline-activated devices.
      * @param license The license to revoke
      */
-    revokeLicense(license: License): Promise<void>;
+    revokeLicense: (license: License) => Promise<void>;
 }
 declare class LicenseClient implements ILicenseClient {
     private readonly configuration;
@@ -239,9 +558,9 @@ declare class LicenseClient implements ILicenseClient {
 }
 
 interface ILicenseStore {
-    loadLocalLicense(): Promise<License | null>;
-    storeLocalLicense(license: License): Promise<void>;
-    deleteLocalLicense(): Promise<void>;
+    loadLocalLicense: () => Promise<License | null>;
+    storeLocalLicense: (license: License) => Promise<void>;
+    deleteLocalLicense: () => Promise<void>;
 }
 declare class InMemoryLicenseStore implements ILicenseStore {
     private license?;
@@ -262,13 +581,19 @@ declare class FileLicenseStore implements ILicenseStore {
 }
 
 interface ILicenseValidator {
-    validateLicense(token: string): Promise<License>;
+    validateLicense: (token: string) => Promise<License>;
 }
 declare class LicenseValidator implements ILicenseValidator {
     private readonly configuration;
     private readonly deviceIdResolver;
     constructor(configuration: MoonbaseConfiguration, deviceIdResolver: IDeviceIdResolver);
     validateLicense(token: string): Promise<License>;
+    /**
+     * Give a {@link IMigratingDeviceIdResolver} the chance to vouch for a device id
+     * this machine used to have. Only consulted after the fast path fails, so
+     * apps that have not opted into a migration pay nothing.
+     */
+    private acceptsHistoricalDeviceId;
     private parseLicenseToken;
 }
 
@@ -279,7 +604,11 @@ declare enum ErrorType {
     LicenseInvalid = "LicenseInvalid",
     LicenseRevoked = "LicenseRevoked",
     LicenseActivationRevoked = "LicenseActivationRevoked",
-    LicenseExpired = "LicenseExpired"
+    LicenseExpired = "LicenseExpired",
+    /** The license is valid but bound to a different device, or to an older fingerprint version. */
+    LicenseDeviceMismatch = "LicenseDeviceMismatch",
+    /** No stable hardware identifier could be read, so no device id can be computed. */
+    DeviceIdentityUnavailable = "DeviceIdentityUnavailable"
 }
 declare class MoonbaseError extends Error {
     readonly title: string;
@@ -288,6 +617,30 @@ declare class MoonbaseError extends Error {
     readonly inner?: Error | undefined;
     constructor(title: string, detail: string | undefined, type?: ErrorType | undefined, inner?: Error | undefined);
 }
+/**
+ * Thrown when the device fingerprint has nothing machine-specific to hash —
+ * either no parameter could be read at all, or the only ones that could are
+ * model-level (vendor, product and board names, shared by every unit of a
+ * product line).
+ *
+ * The spec deliberately makes both an error rather than hashing what is there:
+ * either would hand a whole class of machines the *same* device id, and a license
+ * bound to it would validate on all of them.
+ *
+ * Reachable on platforms with no identity parameters this package can read (BSD
+ * and anything unknown, which the spec leaves undefined, plus Android, whose
+ * `androidId` needs Android-framework API a Node.js process cannot call); when
+ * every source fails — a sandboxed process that cannot spawn `ioreg`, a container
+ * with no DMI, a blocked PowerShell; and on machines whose per-device identifiers
+ * are simply absent, such as a Linux install with no `machine-id` or a VM whose
+ * SMBIOS carries an unset UUID and a blank baseboard serial. Enable the host-name
+ * fallback (`new MoonbaseDeviceIdResolver({ fallback: 'deviceName' })`) to accept
+ * a deliberately weaker id on those machines.
+ */
+declare class InsufficientDeviceIdentityError extends MoonbaseError {
+    readonly platform: string;
+    constructor(platform: string, reason?: string);
+}
 
 interface MoonbaseConfiguration {
     endpoint: string;
@@ -318,7 +671,7 @@ interface MoonbaseConfiguration {
      */
     appVersion?: string;
     licenseStore?: ILicenseStore;
-    deivceIdResolver?: IDeviceIdResolver;
+    deviceIdResolver?: IDeviceIdResolver;
 }
 declare class MoonbaseLicensing {
     private readonly configuration;
@@ -331,4 +684,4 @@ declare class MoonbaseLicensing {
     readRawLicense(license: Buffer): Promise<License>;
 }
 
-export { ActivationMethod, type ActivationRequestResponse, DefaultDeviceIdResolver, type DeviceToken, ErrorType, FileLicenseStore, type IDeviceIdResolver, type ILicenseClient, type ILicenseStore, type ILicenseValidator, InMemoryLicenseStore, type License, LicenseClient, LicenseValidator, type Metadata, type MoonbaseConfiguration, MoonbaseError, MoonbaseLicensing, type Platform, type Product, type User };
+export { ActivationMethod, type ActivationRequestResponse, DEVICE_ID_SOURCE_TAGS, type DeviceIdDescription, type DeviceIdSource, type DeviceIdStamp, type DeviceIdentity, type DeviceIdentityReader, type DeviceToken, ErrorType, FINGERPRINT_PREFIX, FINGERPRINT_VERSION, FileLicenseStore, type FingerprintParam, IDENTIFYING_PARAM_NAMES, type IDescribableDeviceIdResolver, type IDeviceIdResolver, type ILicenseClient, type ILicenseStore, type ILicenseValidator, type IMigratingDeviceIdResolver, InMemoryLicenseStore, InsufficientDeviceIdentityError, LegacyDeviceIdResolver, type License, LicenseClient, LicenseValidator, MAX_VALUE_LENGTH, type Metadata, MigratingDeviceIdResolver, type MoonbaseConfiguration, MoonbaseDeviceIdResolver, type MoonbaseDeviceIdResolverOptions, MoonbaseError, MoonbaseLicensing, type Platform, type PlatformTag, type Product, type User, buildFingerprintMaterial, canonicalizeParams, canonicalizeValue, defaultDeviceIdentityReader, fingerprintDeviceId, fingerprintDigest, identitySource, parseDeviceIdStamp, parseIoregPlatformUuid, parseSmbiosParams, platformTag, selectMachineId, stampDeviceId };