@moonbase.sh/licensing 3.0.0 → 3.1.1

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ActivationMethod: () => ActivationMethod,
+  DEVICE_ID_SOURCE_TAGS: () => DEVICE_ID_SOURCE_TAGS,
   ErrorType: () => ErrorType,
   FINGERPRINT_PREFIX: () => FINGERPRINT_PREFIX,
   FINGERPRINT_VERSION: () => FINGERPRINT_VERSION,
@@ -52,6 +53,7 @@ __export(index_exports, {
   defaultDeviceIdentityReader: () => defaultDeviceIdentityReader,
   fingerprintDeviceId: () => fingerprintDeviceId,
   fingerprintDigest: () => fingerprintDigest,
+  identitySource: () => identitySource,
   parseDeviceIdStamp: () => parseDeviceIdStamp,
   parseIoregPlatformUuid: () => parseIoregPlatformUuid,
   parseSmbiosParams: () => parseSmbiosParams,
@@ -66,6 +68,42 @@ var import_node_process3 = __toESM(require("process"), 1);
 // src/client.ts
 var import_cross_fetch = __toESM(require("cross-fetch"), 1);
 
+// src/errors.ts
+var ErrorType = /* @__PURE__ */ ((ErrorType2) => {
+  ErrorType2["None"] = "None";
+  ErrorType2["ApiError"] = "ApiError";
+  ErrorType2["NoEligibleLicense"] = "NoEligibleLicense";
+  ErrorType2["LicenseInvalid"] = "LicenseInvalid";
+  ErrorType2["LicenseRevoked"] = "LicenseRevoked";
+  ErrorType2["LicenseActivationRevoked"] = "LicenseActivationRevoked";
+  ErrorType2["LicenseExpired"] = "LicenseExpired";
+  ErrorType2["LicenseDeviceMismatch"] = "LicenseDeviceMismatch";
+  ErrorType2["DeviceIdentityUnavailable"] = "DeviceIdentityUnavailable";
+  return ErrorType2;
+})(ErrorType || {});
+var MoonbaseError = class extends Error {
+  constructor(title, detail, type, inner) {
+    super();
+    this.title = title;
+    this.detail = detail;
+    this.type = type;
+    this.inner = inner;
+    this.name = "MoonbaseError";
+    this.message = detail != null ? detail : title;
+  }
+};
+var InsufficientDeviceIdentityError = class extends MoonbaseError {
+  constructor(platform, reason = "no identity parameter could be read") {
+    super(
+      "No device identity",
+      `Could not identify this device (platform: ${platform}): ${reason}`,
+      "DeviceIdentityUnavailable" /* DeviceIdentityUnavailable */
+    );
+    this.platform = platform;
+    this.name = "InsufficientDeviceIdentityError";
+  }
+};
+
 // src/schemas.ts
 var import_zod = require("zod");
 
@@ -82,6 +120,11 @@ var activationRequestResponseSchema = import_zod.z.object({
   request: import_zod.z.string(),
   browser: import_zod.z.string()
 });
+var problemDetailsSchema = import_zod.z.object({
+  title: import_zod.z.string().nullish(),
+  detail: import_zod.z.string().nullish(),
+  errorType: import_zod.z.string().nullish()
+});
 var productSchema = import_zod.z.object({
   id: import_zod.z.string(),
   name: import_zod.z.string(),
@@ -136,7 +179,7 @@ var LicenseClient = class {
       body: JSON.stringify(content)
     });
     if (response.status >= 400) {
-      throw new MoonbaseError("Request not successful", `The API responded with a ${response.status} ${response.statusText} response`, "ApiError" /* ApiError */);
+      throw await errorFromResponse(response);
     }
     try {
       return activationRequestResponseSchema.parse(await response.json());
@@ -201,12 +244,12 @@ var LicenseClient = class {
       body: license.token
     });
     if (response.status >= 400) {
-      throw new MoonbaseError("Request not successful", `The API responded with a ${response.status} ${response.statusText} response`, "ApiError" /* ApiError */);
+      throw await errorFromResponse(response);
     }
   }
   async handleLicenseResponse(response) {
     if (response.status >= 400) {
-      throw new MoonbaseError("Request not successful", `The API responded with a ${response.status} ${response.statusText} response`, "ApiError" /* ApiError */);
+      throw await errorFromResponse(response);
     }
     return await this.licenseValidator.validateLicense(await response.text());
   }
@@ -227,6 +270,35 @@ var LicenseClient = class {
     return `?${parts.join("&")}`;
   }
 };
+var licenseErrorTypes = /* @__PURE__ */ new Set([
+  "NoEligibleLicense" /* NoEligibleLicense */,
+  "LicenseInvalid" /* LicenseInvalid */,
+  "LicenseRevoked" /* LicenseRevoked */,
+  "LicenseActivationRevoked" /* LicenseActivationRevoked */,
+  "LicenseExpired" /* LicenseExpired */
+]);
+async function errorFromResponse(response) {
+  const fallback = new MoonbaseError(
+    "Request not successful",
+    `The API responded with a ${response.status} ${response.statusText} response`,
+    "ApiError" /* ApiError */
+  );
+  let body;
+  try {
+    body = JSON.parse(await response.text());
+  } catch (e) {
+    return fallback;
+  }
+  const problem = problemDetailsSchema.safeParse(body);
+  if (!problem.success)
+    return fallback;
+  const { title, detail, errorType } = problem.data;
+  return new MoonbaseError(
+    title != null ? title : fallback.title,
+    detail != null ? detail : fallback.detail,
+    errorType && licenseErrorTypes.has(errorType) ? errorType : "ApiError" /* ApiError */
+  );
+}
 
 // src/deviceIdResolver.ts
 var import_node_child_process2 = __toESM(require("child_process"), 1);
@@ -235,42 +307,6 @@ var import_node_os2 = __toESM(require("os"), 1);
 var import_node_process2 = __toESM(require("process"), 1);
 var import_systeminformation = __toESM(require("systeminformation"), 1);
 
-// src/errors.ts
-var ErrorType = /* @__PURE__ */ ((ErrorType2) => {
-  ErrorType2["None"] = "None";
-  ErrorType2["ApiError"] = "ApiError";
-  ErrorType2["NoEligibleLicense"] = "NoEligibleLicense";
-  ErrorType2["LicenseInvalid"] = "LicenseInvalid";
-  ErrorType2["LicenseRevoked"] = "LicenseRevoked";
-  ErrorType2["LicenseActivationRevoked"] = "LicenseActivationRevoked";
-  ErrorType2["LicenseExpired"] = "LicenseExpired";
-  ErrorType2["LicenseDeviceMismatch"] = "LicenseDeviceMismatch";
-  ErrorType2["DeviceIdentityUnavailable"] = "DeviceIdentityUnavailable";
-  return ErrorType2;
-})(ErrorType || {});
-var MoonbaseError = class extends Error {
-  constructor(title, detail, type, inner) {
-    super();
-    this.title = title;
-    this.detail = detail;
-    this.type = type;
-    this.inner = inner;
-    this.name = "MoonbaseError";
-    this.message = detail != null ? detail : title;
-  }
-};
-var InsufficientDeviceIdentityError = class extends MoonbaseError {
-  constructor(platform, reason = "no identity parameter could be read") {
-    super(
-      "No device identity",
-      `Could not identify this device (platform: ${platform}): ${reason}`,
-      "DeviceIdentityUnavailable" /* DeviceIdentityUnavailable */
-    );
-    this.platform = platform;
-    this.name = "InsufficientDeviceIdentityError";
-  }
-};
-
 // src/fingerprint.ts
 var import_node_buffer = require("buffer");
 var import_node_child_process = __toESM(require("child_process"), 1);
@@ -283,7 +319,20 @@ var FINGERPRINT_VERSION = 2;
 var MAX_VALUE_LENGTH = 128;
 var PRINTABLE_ASCII_MIN = 32;
 var PRINTABLE_ASCII_MAX = 126;
-var STAMP_PATTERN = /^mbd(\d+)(n?)_([0-9a-f]{64})$/;
+var SOURCE_TAGS = {
+  identity: "",
+  deviceName: "n",
+  scoped: "s"
+};
+var DEVICE_ID_SOURCE_TAGS = Object.freeze({ ...SOURCE_TAGS });
+var SOURCE_BY_TAG = new Map(
+  Object.entries(SOURCE_TAGS).map(([source, tag]) => [tag, source])
+);
+var SCOPED_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+function identitySource(platform) {
+  return SCOPED_PLATFORMS.has(platform) ? "scoped" : "identity";
+}
+var STAMP_PATTERN = /^mbd(\d+)([a-z]*)_([0-9a-f]{64})$/;
 function canonicalizeValue(value) {
   var _a;
   let printable = "";
@@ -294,6 +343,12 @@ function canonicalizeValue(value) {
   }
   return printable.slice(0, MAX_VALUE_LENGTH).replace(/^ +| +$/g, "");
 }
+var PLATFORM_TAGS = /* @__PURE__ */ new Set(
+  ["mac", "ios", "windows", "android", "linux", "bsd", "unknown"]
+);
+function isPlatformTag(value) {
+  return PLATFORM_TAGS.has(value);
+}
 function platformTag(platform = import_node_process.default.platform) {
   switch (platform) {
     case "darwin":
@@ -309,7 +364,7 @@ function platformTag(platform = import_node_process.default.platform) {
     case "netbsd":
       return "bsd";
     default:
-      return "unknown";
+      return isPlatformTag(platform) ? platform : "unknown";
   }
 }
 var IDENTIFYING_PARAMS = /* @__PURE__ */ new Set([
@@ -317,6 +372,8 @@ var IDENTIFYING_PARAMS = /* @__PURE__ */ new Set([
   "machineId",
   "systemUuid",
   "baseboardSerialNumber",
+  "identifierForVendor",
+  "androidId",
   "deviceName"
 ]);
 var IDENTIFYING_PARAM_NAMES = Object.freeze([...IDENTIFYING_PARAMS]);
@@ -341,9 +398,35 @@ var NOT_PROGRAMMED_VALUES = /* @__PURE__ */ new Set([
   // deployed from such an image reads it, so it is the opposite of an identifier.
   "uninitialized"
 ]);
+var IDENTITY_CONSTRAINTS = {
+  androidId: {
+    // Reading the *static field* `Settings.Secure.ANDROID_ID` instead of calling
+    // `getString` with it yields the key name "android_id", identical on every
+    // device, so a single activation would unlock a whole Android install base.
+    // That string is not hex, so this stops it reaching the material.
+    //
+    // The bound is 1,16 and not 16 because AOSP before 8.0 generated the value
+    // with `Long.toHexString`, which drops leading zeros — a strict 16 would
+    // reject legitimate ids on roughly one in sixteen pre-Oreo devices.
+    format: /^[0-9a-f]{1,16}$/,
+    // A real ANDROID_ID shared by a large batch of 2010-era devices whose
+    // `ro.serialno` was unset, seeding the generator identically on every unit.
+    // Valid hex, so the format rule cannot catch it.
+    rejected: /* @__PURE__ */ new Set(["9774d56d682e549c"])
+  }
+};
 function isNotProgrammed(value) {
   return NOT_PROGRAMMED_VALUES.has(value.toLowerCase()) || /^0+$/.test(value) || /^f+$/i.test(value);
 }
+function isUsableIdentity(name, value) {
+  var _a, _b, _c;
+  if (isNotProgrammed(value))
+    return false;
+  const constraint = IDENTITY_CONSTRAINTS[name];
+  if (!constraint)
+    return true;
+  return ((_b = (_a = constraint.format) == null ? void 0 : _a.test(value)) != null ? _b : true) && !((_c = constraint.rejected) == null ? void 0 : _c.has(value.toLowerCase()));
+}
 function canonicalizeParams(params) {
   const kept = [];
   const seen = /* @__PURE__ */ new Set();
@@ -351,7 +434,7 @@ function canonicalizeParams(params) {
     const value = canonicalizeValue(rawValue);
     if (value.length === 0)
       continue;
-    if (IDENTIFYING_PARAMS.has(name) && isNotProgrammed(value))
+    if (IDENTIFYING_PARAMS.has(name) && !isUsableIdentity(name, value))
       continue;
     if (seen.has(name))
       throw new Error(`Duplicate fingerprint parameter name: ${name}`);
@@ -364,6 +447,12 @@ function buildFingerprintMaterial(platform, params) {
   const kept = canonicalizeParams(params);
   if (kept.length === 0)
     throw new InsufficientDeviceIdentityError(platform, "no identity parameter could be read");
+  if (SCOPED_PLATFORMS.has(platform) && kept.some(([name]) => name === "deviceName")) {
+    throw new InsufficientDeviceIdentityError(
+      platform,
+      "the host-name fallback is not available on this platform, where the host name is the same on every device"
+    );
+  }
   if (!kept.some(([name]) => IDENTIFYING_PARAMS.has(name))) {
     throw new InsufficientDeviceIdentityError(
       platform,
@@ -379,18 +468,20 @@ function fingerprintDigest(material) {
   return (0, import_node_crypto.createHash)("sha256").update(material, "utf8").digest("hex");
 }
 function stampDeviceId(digest, source = "identity") {
-  return `mbd${FINGERPRINT_VERSION}${source === "deviceName" ? "n" : ""}_${digest}`;
+  return `mbd${FINGERPRINT_VERSION}${SOURCE_TAGS[source]}_${digest}`;
 }
 function fingerprintDeviceId(material, source = "identity") {
   return stampDeviceId(fingerprintDigest(material), source);
 }
 function parseDeviceIdStamp(deviceId) {
+  var _a;
   const match = STAMP_PATTERN.exec(deviceId);
   if (!match)
     return null;
   return {
     version: Number(match[1]),
-    source: match[2] === "n" ? "deviceName" : "identity",
+    sourceTag: match[2],
+    source: (_a = SOURCE_BY_TAG.get(match[2])) != null ? _a : null,
     digest: match[3]
   };
 }
@@ -519,18 +610,23 @@ function readWindowsIdentity() {
   return { params: parseSmbiosParams(readWindowsSmbios()), deviceName: import_node_os.default.hostname() };
 }
 function defaultDeviceIdentityReader(platform = import_node_process.default.platform) {
+  const tag = platformTag(platform);
   return {
     read() {
-      switch (platform) {
-        case "darwin":
+      switch (tag) {
+        case "mac":
           return readMacIdentity();
         case "linux":
           return readLinuxIdentity();
-        case "win32":
+        case "windows":
           return readWindowsIdentity();
-        // android, bsd and anything else define no identity params: the spec
-        // has no stable hardware source for them, so they resolve to an
+        // Everything else yields no identity params here, so it resolves to an
         // insufficient-identity error unless the deviceName fallback is enabled.
+        // For bsd and unknown that matches the spec, which defines none. Android
+        // is different: the spec *does* define `androidId`, but it comes from
+        // `Settings.Secure.getString`, which is Android-framework API that a
+        // Node.js process cannot reach. Collecting it is the C++/.NET SDKs' job.
+        // A host that can bridge it should supply its own DeviceIdentityReader.
         default:
           return { params: [], deviceName: import_node_os.default.hostname() };
       }
@@ -582,7 +678,7 @@ var MoonbaseDeviceIdResolver = class {
   computeDescription() {
     const { params, deviceName } = this.readIdentity();
     try {
-      return this.describe(params, "identity");
+      return this.describe(params, identitySource(this.platform));
     } catch (err) {
       if (this.fallback !== "deviceName" || !(err instanceof InsufficientDeviceIdentityError))
         throw err;
@@ -829,25 +925,48 @@ var LicenseValidator = class {
 };
 function deviceMismatchError(expected, bound) {
   const detail = "This license is not for this device";
-  const versionNote = describeVersionDifference(expected, bound);
+  const stampNote = describeStampDifference(expected, bound);
   return new MoonbaseError(
     "License is for another device",
-    versionNote ? `${detail}. ${versionNote}` : detail,
+    stampNote ? `${detail}. ${stampNote}` : detail,
     "LicenseDeviceMismatch" /* LicenseDeviceMismatch */
   );
 }
-function describeVersionDifference(expected, bound) {
+function describeStampDifference(expected, bound) {
   const expectedStamp = parseDeviceIdStamp(expected);
   if (!expectedStamp)
     return null;
   const boundStamp = parseDeviceIdStamp(bound);
-  if (boundStamp && boundStamp.version === expectedStamp.version)
-    return null;
-  if (boundStamp && boundStamp.version > expectedStamp.version) {
-    return `The binding was created by device fingerprint v${boundStamp.version}, which is newer than the v${expectedStamp.version} this SDK computes \u2014 update the SDK rather than re-activating, which would rebind the device to the older algorithm.`;
+  if (!boundStamp || boundStamp.version !== expectedStamp.version)
+    return describeVersionDifference(expectedStamp, boundStamp);
+  if (boundStamp.sourceTag !== expectedStamp.sourceTag)
+    return describeSourceDifference(expectedStamp, boundStamp);
+  return null;
+}
+function describeVersionDifference(expected, bound) {
+  if (bound && bound.version > expected.version) {
+    return `The binding was created by device fingerprint v${bound.version}, which is newer than the v${expected.version} this SDK computes \u2014 update the SDK rather than re-activating, which would rebind the device to the older algorithm.`;
+  }
+  const boundVersion = bound ? `device fingerprint v${bound.version}` : "an SDK predating versioned device fingerprints";
+  return `The binding was created by ${boundVersion}, while this SDK computes v${expected.version}, so this may instead be the same machine bound under the older algorithm \u2014 re-activate to find out, or configure a MigratingDeviceIdResolver to keep accepting the previous id.`;
+}
+function describeSourceDifference(expected, bound) {
+  if (bound.source === "scoped") {
+    return "The binding uses an app-scoped device identity, which cannot be compared with the id this SDK computes \u2014 not even on the same device. Re-activate here to bind this build.";
+  }
+  if (expected.source === "scoped") {
+    return "This SDK computes an app-scoped device identity, which cannot be compared with the one the binding carries \u2014 not even on the same device. Re-activate here to bind this app.";
+  }
+  if (bound.source === null) {
+    return `The binding carries the device identity tag "${bound.sourceTag}", which this SDK does not recognise \u2014 it was created by a newer Moonbase SDK, so update rather than re-activating.`;
+  }
+  if (expected.source === null) {
+    return `The id this SDK computes carries the device identity tag "${expected.sourceTag}", which the spec does not define \u2014 it came from a custom device id resolver, so check that resolver rather than the binding.`;
+  }
+  if (bound.source === "deviceName") {
+    return "The binding was created from the host-name fallback, while this SDK reads hardware identity, so this may instead be the same machine bound while no hardware identity could be read \u2014 re-activate to find out.";
   }
-  const boundVersion = boundStamp ? `device fingerprint v${boundStamp.version}` : "an SDK predating versioned device fingerprints";
-  return `The binding was created by ${boundVersion}, while this SDK computes v${expectedStamp.version}, so this may instead be the same machine bound under the older algorithm \u2014 re-activate to find out, or configure a MigratingDeviceIdResolver to keep accepting the previous id.`;
+  return "The binding was created from hardware identity, while this SDK has fallen back to the host name \u2014 check why hardware identity cannot be read here rather than re-activating, which would rebind the device to the weaker id.";
 }
 
 // src/index.ts
@@ -895,6 +1014,7 @@ var MoonbaseLicensing = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActivationMethod,
+  DEVICE_ID_SOURCE_TAGS,
   ErrorType,
   FINGERPRINT_PREFIX,
   FINGERPRINT_VERSION,
@@ -916,6 +1036,7 @@ var MoonbaseLicensing = class {
   defaultDeviceIdentityReader,
   fingerprintDeviceId,
   fingerprintDigest,
+  identitySource,
   parseDeviceIdStamp,
   parseIoregPlatformUuid,
   parseSmbiosParams,

package/dist/index.d.cts

@@ -33,11 +33,30 @@ declare const FINGERPRINT_VERSION = 2;
 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, stamped
- * distinctly so a server can tell the two apart.
+ * `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';
-type PlatformTag = 'mac' | 'windows' | 'android' | 'linux' | 'bsd' | 'unknown';
+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. */
@@ -53,7 +72,10 @@ interface DeviceIdentityReader {
 interface DeviceIdStamp {
     /** Fingerprint spec version that produced the digest. */
     version: number;
-    source: DeviceIdSource;
+    /** 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;
 }
@@ -69,8 +91,23 @@ interface DeviceIdStamp {
  * 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. */
-declare function platformTag(platform?: NodeJS.Platform): PlatformTag;
+/**
+ * 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.
  *
@@ -107,9 +144,12 @@ declare function stampDeviceId(digest: string, source?: DeviceIdSource): string;
 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 (a legacy id, or one from a custom resolver). Lets a validator tell
+ * 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`). */
@@ -136,7 +176,7 @@ declare function selectMachineId(...sources: string[]): string;
  */
 declare function parseSmbiosParams(smbiosData: Buffer): FingerprintParam[];
 /** The real, platform-dispatching identity reader used by {@link MoonbaseDeviceIdResolver}. */
-declare function defaultDeviceIdentityReader(platform?: NodeJS.Platform): DeviceIdentityReader;
+declare function defaultDeviceIdentityReader(platform?: NodeJS.Platform | PlatformTag): DeviceIdentityReader;
 
 interface IDeviceIdResolver {
     resolveDeviceName: () => Promise<string>;
@@ -181,8 +221,16 @@ interface IMigratingDeviceIdResolver extends IDeviceIdResolver {
 interface MoonbaseDeviceIdResolverOptions {
     /** Overrides the identity source. Primarily for testing. */
     reader?: DeviceIdentityReader;
-    /** Overrides the detected platform. Primarily for testing. */
-    platform?: NodeJS.Platform;
+    /**
+     * 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
@@ -190,6 +238,10 @@ interface MoonbaseDeviceIdResolverOptions {
      *
      * 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';
 }
@@ -545,13 +597,28 @@ declare class LicenseValidator implements ILicenseValidator {
     private parseLicenseToken;
 }
 
+/**
+ * What went wrong, on a {@link MoonbaseError}. The license types say the license
+ * is no longer usable, so a stored copy can be deleted. `ApiError` only says no
+ * answer was had: keep the stored license and try again later.
+ */
 declare enum ErrorType {
     None = "None",
+    /**
+     * The request failed without saying anything about the license: an outage, a
+     * rate limit, a proxy error page. Transient, so keep any stored license. A
+     * network failure is not a `MoonbaseError` at all, and is transient too.
+     */
     ApiError = "ApiError",
+    /** The customer has no license for this product to activate. */
     NoEligibleLicense = "NoEligibleLicense",
+    /** The license token failed verification (signature, issuer or product), or the stored license could not be read. */
     LicenseInvalid = "LicenseInvalid",
+    /** The merchant revoked the license, for example after a refund. */
     LicenseRevoked = "LicenseRevoked",
+    /** This device's activation was revoked, freeing its seat. The license itself may still be active. */
     LicenseActivationRevoked = "LicenseActivationRevoked",
+    /** The license, or trial, has expired. */
     LicenseExpired = "LicenseExpired",
     /** The license is valid but bound to a different device, or to an older fingerprint version. */
     LicenseDeviceMismatch = "LicenseDeviceMismatch",
@@ -575,14 +642,15 @@ declare class MoonbaseError extends Error {
  * 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 defined identity parameters (Android, BSD,
- * anything unknown); 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.
+ * 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;
@@ -631,4 +699,4 @@ declare class MoonbaseLicensing {
     readRawLicense(license: Buffer): Promise<License>;
 }
 
-export { ActivationMethod, type ActivationRequestResponse, 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, parseDeviceIdStamp, parseIoregPlatformUuid, parseSmbiosParams, platformTag, selectMachineId, stampDeviceId };
+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 };