@moonbase.sh/licensing 3.0.0 → 3.1.0

package/FINGERPRINT_SPEC.md

@@ -7,6 +7,13 @@ machine **device id**. Any two SDKs that conform compute the same id on a given
 license bound by one validates in the other. SDKs adopt the spec independently, so conformance is a
 property of a given SDK version, not something to assume.
 
+On iOS and Android that guarantee is narrower, because neither exposes an identifier an unrelated
+app can read. Those platforms use a [scoped identity](#scoped-identity), whose value is tied to the
+app it runs in, so **two apps** on one device compute different ids by design and the `mbd2s_` stamp
+marks it. The algorithm is unchanged: two conforming SDKs embedded in the *same* app still compute
+the same id. What varies is the scope, never the implementation — an SDK that computed something
+different from its peers in the same app would be non-conforming, not scoped.
+
 Implement against this document and prove it against
 [`fingerprint-vectors.json`](./fingerprint-vectors.json), the machine-readable conformance suite
 shipped alongside it. If an SDK disagrees with this spec, the SDK is the bug. If this spec
@@ -21,8 +28,11 @@ divergence by defining a byte-exact, deterministic algorithm.
 
 ## Stability contract
 
-The algorithm answers one question: *is this the same machine?* Every parameter choice below must
-satisfy this table, and any proposed change must be argued against it.
+The algorithm answers one question: *is this the same machine?* Every hardware-identity parameter
+below must satisfy this table, and any proposed change must be argued against it. The two
+[scoped](#scoped-identity) parameters cannot satisfy it and are governed by a
+[weaker contract](#what-scoped-identity-guarantees) instead — that gap is the whole reason they are
+stamped differently.
 
 | Event | The device id must |
 |---|---|
@@ -69,8 +79,29 @@ device_id = "mbd" + version + source_tag + "_" + digest
 For this version: `mbd2_` plus 64 hex characters, 69 in total. It uses only RFC 3986 unreserved
 characters, so it never needs escaping in a URL, JSON body, file name or shell command.
 
-`source_tag` is empty for a normal hardware fingerprint, and `n` for the opt-in host-name fallback
-(`mbd2n_`, see [Insufficient identity](#insufficient-identity)).
+`source_tag` records how the identity was obtained, and therefore what the id may be compared to:
+
+| Tag | Form | Meaning |
+|---|---|---|
+| *(empty)* | `mbd2_` | Hardware identity. Comparable across every conforming SDK on that machine. |
+| `n` | `mbd2n_` | The opt-in host-name fallback. See [Insufficient identity](#insufficient-identity). |
+| `s` | `mbd2s_` | [Scoped identity](#scoped-identity): stable for the device within one [scope](#what-the-scope-actually-is), and **not** comparable across scopes. |
+
+Those are the tags this version **defines**. The grammar an SDK **accepts** is deliberately wider:
+
+```
+^mbd(\d+)([a-z]*)_([0-9a-f]{64})$
+```
+
+A parser MUST accept a source tag it does not recognise, treating the id as opaque and comparing it
+literally rather than rejecting it. That is what lets a new tag be introduced without a version bump,
+so it must be possible to *parse* `mbd2x_…` while knowing only that `x` is not a tag this SDK
+defines. An SDK that hard-codes the three defined tags into its pattern cannot do that, and will
+report a perfectly valid id from a newer SDK as "not a Moonbase device id".
+
+The tag is `[a-z]*`, not a single optional character, so a future two-letter tag needs no version
+bump either. `_` terminates it, and digits cannot appear in it, so the split from `version` is
+unambiguous.
 
 ### Why the id is stamped
 
@@ -160,6 +191,8 @@ Exactly these parameters count as **identifying**, describing the individual mac
 | `machineId` | Linux |
 | `systemUuid` | Windows |
 | `baseboardSerialNumber` | Windows |
+| `identifierForVendor` | iOS ([scoped](#scoped-identity)) |
+| `androidId` | Android ([scoped](#scoped-identity)) |
 | `deviceName` | the opt-in host-name fallback only |
 
 At least one must survive canonicalization, or the result is
@@ -179,6 +212,18 @@ product line. Compared case-insensitively against the canonical value:
 `not available`, `none`, `unknown`, `invalid`, `n/a`, `0123456789`, `uninitialized`, plus any value
 that is entirely `0`s or entirely `f`/`F`s (a blank UUID field, a zeroed `machine-id`).
 
+One of those earns its place on mobile: `unknown` is exactly what Android's `Build.SERIAL` returns
+without a privileged permission, so an SDK that reaches for it lands on a fleet-wide constant.
+
+**Per-parameter rejections.** A constant that belongs to *one* platform's identifier is rejected for
+that parameter only, never added to the list above. Widening it would change the device id of a
+machine that happens to report the same string as some unrelated field, and any change that alters
+the output for an unchanged machine requires a version bump. Currently there is one:
+
+| Parameter | Also rejected | Why |
+|---|---|---|
+| `androidId` | `9774d56d682e549c` | 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. It is valid hex, so the format rule cannot catch it. |
+
 This applies to **identifying parameters only**. A descriptive field reading `Default string` is
 still a fair description of the model and stays in the material. A serial number reading it is not a
 serial number.
@@ -188,12 +233,36 @@ serial number.
 | OS family | Tag |
 |---|---|
 | macOS | `mac` |
+| iOS, iPadOS, tvOS, watchOS, visionOS | `ios` |
 | Windows | `windows` |
 | Linux | `linux` |
 | Android | `android` |
 | FreeBSD / OpenBSD / NetBSD | `bsd` |
 | anything else | `unknown` |
 
+Every Apple platform other than macOS maps to `ios`, because they all offer the same single
+identifier and nothing else (watchOS via `WKInterfaceDevice`, the rest via `UIDevice`). Giving them
+one tag is what keeps two SDKs from disagreeing: the tag is hashed into the material, so an SDK that
+mapped tvOS to `unknown` while another mapped it to `ios` would compute different ids on one device.
+
+> **The tag follows the OS the process is running on, not the SDK it was built against.** One Apple
+> binary can run in three ways, and the obvious tests (`#if targetEnvironment(macCatalyst)`,
+> `#if os(iOS)`, `UIDevice.systemName`) all get it wrong — a Mac Catalyst build compiles with
+> `os(iOS)` true and reports `systemName` as `iPadOS` while running on macOS. Use the runtime pair:
+>
+> | `isMacCatalystApp` | `isiOSAppOnMac` | Running as | Tag |
+> |---|---|---|---|
+> | `false` | `false` | a real iPhone / iPad | `ios` |
+> | `true` | `false` | Mac Catalyst | `mac` |
+> | `true` | `true` | an iOS app on Apple silicon | `ios` |
+>
+> Mac Catalyst is the case that matters: it can read **both** `identifierForVendor` and IOKit
+> `IOPlatformUUID` (the macOS App Sandbox does not deny IOKit property reads), so without a rule two
+> SDKs on one Mac would disagree about which one to use. Hardware identity wins, per
+> [Scoped identity](#scoped-identity). An unmodified iOS app on Apple silicon cannot reach IOKit, so
+> it stays on the scoped path and its id is not comparable with the Catalyst one — which the `mbd2s_`
+> stamp already says.
+
 ## Identity parameters per platform
 
 Parameters **must** appear in the order listed. Reads are best-effort: a missing or unreadable
@@ -295,11 +364,115 @@ SMBIOS structure walking:
 - An all-`00` or all-`FF` `systemUuid` means "not set" and is treated as **absent**, so fleets of VMs
   with unset UUIDs cannot collide.
 
-### Android (`android`), BSD (`bsd`), other (`unknown`)
+### iOS (`ios`) and Android (`android`) — scoped
+
+Both platforms deliberately removed every device identifier that unrelated applications can read.
+An SDK on them MAY emit a [scoped identity](#scoped-identity); it has nothing else to offer.
+
+| Platform | Order | Name | Identifying | Source |
+|---|---|---|---|---|
+| iOS | 1 | `identifierForVendor` | ✅ | `[[UIDevice currentDevice] identifierForVendor].UUIDString`, with all `-` removed and **uppercased**, matching `ioPlatformUuid`. On watchOS, `[[WKInterfaceDevice currentDevice] identifierForVendor]` |
+| Android | 1 | `androidId` | ✅ | `Settings.Secure.getString(contentResolver, ANDROID_ID)`, lowercased. Must match `^[0-9a-f]{1,16}$` once canonicalized, or it is treated as **absent** |
+
+> The Android value must come from `Settings.Secure.getString`. Reading the static field
+> `Settings.Secure.ANDROID_ID` yields the string constant `"android_id"`, which is the *key name* and
+> is identical on every device. An SDK that hashes it gives its entire Android install base one
+> device id, so a single activation unlocks every device. This is not hypothetical: JUCE's
+> `SystemStats::getUniqueDeviceID()` reads the static field via `GetStaticObjectField`, never
+> touching a `ContentResolver`, and still does so in 9.0.0 — so every JUCE Android app returns the
+> same value. Its `jassert` that the result is non-empty never fires, because the hash of a constant
+> is not empty. The defect is silent.
+
+The `^[0-9a-f]{1,16}$` rule is what makes that mistake *mechanically* impossible rather than merely
+documented: `"android_id"` is not hex, so it never reaches 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.
+
+Either value **may be absent**, and then resolves to
+[insufficient identity](#insufficient-identity) rather than to a constant. Apple gives "after the
+device has been restarted but before the user has unlocked it" as *an example* of when
+`identifierForVendor` is `nil`, not an exhaustive list; on Android the value is generated lazily and
+`getString` can return null. Treat absence as normal and retry later rather than assuming a cause.
+
+### BSD (`bsd`), other (`unknown`)
 
 No identity parameters are defined. These platforms always resolve to
 [insufficient identity](#insufficient-identity).
 
+## Scoped identity
+
+A **scoped** device id is stable for a given device within one *scope*, and carries no meaning
+outside it. It exists because some platforms provide nothing better. The unscoped alternatives are
+gone: iOS has not exposed a hardware serial since iOS 7, Android `Build.SERIAL` returns `unknown`
+without a privileged permission from Android 10, IMEI requires `READ_PRIVILEGED_PHONE_STATE`, and
+MAC addresses are randomised.
+
+### What the scope actually is
+
+"One publisher" is a useful shorthand and a poor rule, because neither platform scopes by publisher.
+Be precise, because the difference is observable:
+
+| Platform | Scope key |
+|---|---|
+| iOS | The **vendor**: determined by App Store data, and for apps installed any other way, every component of the reverse-DNS bundle id *except the last*. Not the Team ID. |
+| Android, API 26+ | The **app signing key**, per OS user, per device. |
+| Android, before API 26 | The **device and OS user** only. Every app on the device reads the same value. |
+
+So `com.example.editor` and `com.example.player` share an iOS scope, while the same publisher's two
+Android apps signed with different keys do **not** share an Android one on API 26 or later. An SDK
+must never assume that "same publisher" means "same scope".
+
+> Per-signing-key scoping arrived in Android 8.0. Older devices are still in scope for this spec —
+> the `^[0-9a-f]{1,16}$` rule below deliberately accepts the shorter ids they generate — and on them
+> `ANDROID_ID` is a single per-device value that every installed app can read. That makes the scope
+> *wider* than the table's first Android row, never narrower, so treating those ids as scoped is
+> conservative rather than unsound: the rules below forbid correlating them, which is still correct
+> when they happen to be correlatable. It does mean two unrelated apps on one pre-Oreo device compute
+> the **same** scoped id, so a server must not infer distinct devices from distinct ids, nor one
+> device from one id.
+
+### What scoped identity guarantees
+
+Scoped ids are stamped `mbd2s_` so the limitation travels with the value.
+
+**The stamp follows the platform, not the call site.** Any id built from the identity parameters of a
+scoped platform is scoped, whatever collected them: an SDK's own reader, a host bridging
+`identifierForVendor` through platform API, an embedder assembling the material itself. Derive the
+source from the platform tag rather than letting a caller pass it, because the one thing that cannot
+happen is a scoped value going out stamped `mbd2_`. That would tell the server it is a hardware
+fingerprint comparable across every app on the device, and the server would then be entitled to
+correlate exactly the ids the rules below forbid correlating.
+
+Those rules are what the stamp promises:
+
+- Two scoped ids from **different scopes are not comparable at all**. Equal values do not imply the
+  same device, and different values do not imply different devices. A validator, a server and an
+  analytics pipeline must all refuse to correlate them.
+- A scoped id and an unscoped one are likewise never comparable, so a machine that could produce
+  both must not be given a scoped id. See the Mac Catalyst rule under [Platform tags](#platform-tags).
+- Everything else is unchanged: same canonicalization, same material grammar, same digest.
+
+Within one scope the [stability contract](#stability-contract) holds for every hardware event in it —
+renames, network changes, OS upgrades. But scoped values also move for reasons no hardware
+identifier does, and this table, not that one, is what `mbd2s_` promises:
+
+| Event | The device id may |
+|---|---|
+| App reinstalled, iOS, at least one other app from the vendor still installed | **not** change |
+| App reinstalled, Android, same signing key | **not** change |
+| **Every** app from that vendor deleted, then one reinstalled (iOS) | change |
+| Installed by Xcode or ad-hoc distribution rather than the App Store (iOS) | change |
+| App signing key rotated between uninstall and reinstall (Android, API 26+) | change |
+| Device factory reset | change |
+| A different OS user on the same device (Android) | change |
+| App transferred to another App Store team (iOS) | change |
+
+Every "change" row costs the user a re-activation. That is the price of the platform, not a defect
+to be engineered around — the only way to avoid it is an identifier neither platform offers.
+
+Scoped identity is a floor, not a preference. An SDK MUST use hardware identity where the platform
+provides it, and MAY use a scoped identity only where it does not.
+
 ## Insufficient identity
 
 An SDK **must** raise an error when no parameter survives canonicalization, or when none of the
@@ -316,6 +489,19 @@ parameters. The material is then the single parameter `deviceName=<host name>`,
 be stamped `mbd2n_` so the weaker binding is visible to the server and to support. If the host name
 is empty too, that is still insufficient identity.
 
+> **The host-name fallback MUST NOT be offered on `ios` or `android`.** On those platforms the host
+> name is not weak identity, it is not identity at all: since iOS 17 `gethostname()` and
+> `utsname.nodename` return the literal `localhost` on every device, and since iOS 16
+> `UIDevice.name` returns the model name — `"iPhone"` — regardless of which SDK the app was built
+> against. The entitlement that restores the user-assigned name is granted only to apps that do not
+> use it for fingerprinting, so it is closed to licensing by policy as well as by API.
+>
+> An iOS SDK that fell through to this fallback when `identifierForVendor` was momentarily absent
+> would hand its **entire install base one device id**, and a single activation would unlock every
+> device — exactly the catastrophe this section exists to prevent, reached by following the section
+> above it. On those platforms the ladder is [scoped identity](#scoped-identity), then insufficient
+> identity, and nothing else. Absence is transient: raise the error and retry later.
+
 ## Device name
 
 A human-readable label sent alongside the device id at activation. It is **not** part of the
@@ -325,8 +511,15 @@ license.
 | Platform | Source |
 |---|---|
 | macOS | host name, with a trailing `.local` removed (case-insensitive) |
+| iOS | `UIDevice.name` (the model name on iOS 16+), or the empty string |
+| Android | `Settings.Global.DEVICE_NAME`, falling back to `Build.MODEL`, or the empty string |
 | other | host name |
 
+On iOS and Android this label is close to worthless for telling two devices apart — it is the model
+name on most modern devices. That is tolerable *because it is only a label*: it never enters the
+material on those platforms, since the host-name fallback is forbidden there. An empty value is fine;
+the server treats the label as decoration, not identity.
+
 ## Worked examples
 
 Reproduced by [`fingerprint-vectors.json`](./fingerprint-vectors.json), which contains these and
@@ -368,6 +561,24 @@ baseboardSerialNumber=BSN-42
 ```
 → `mbd2_fadd75457e44f669e9865caff122b4706a4501089ac9e73b8735139bf57676ad`
 
+**iOS** — scoped, note the `s`:
+
+```
+moonbase:fingerprint:v2
+platform=ios
+identifierForVendor=0123456789ABCDEF0123456789ABCDEF
+```
+→ `mbd2s_298ced47f8d983939db1d5fce6d4b4f2f8766aa19e3e17536fcd1604a81febf1`
+
+**Android** — also scoped:
+
+```
+moonbase:fingerprint:v2
+platform=android
+androidId=a1b2c3d4e5f60718
+```
+→ `mbd2s_ca988ecf5c529964bfaa80734da3dbe070dd41881aa43f8c472f3a5d512b4eff`
+
 **Opt-in host-name fallback** (note the `n`):
 
 ```
@@ -380,7 +591,11 @@ deviceName=PC-1
 ## Conformance checklist
 
 Run [`fingerprint-vectors.json`](./fingerprint-vectors.json) in your SDK's test suite. It covers
-every item below; this list is what to look at when a vector fails.
+every item in the first list; that list is what to look at when a vector fails. The second list is
+about *behaviour around* the id rather than its computation, so no vector can settle it — review it
+by hand.
+
+**Covered by the vectors:**
 
 - [ ] Material prefix is exactly `moonbase:fingerprint:v2`.
 - [ ] Lines are **joined** with a single LF, and the material has **no trailing newline**.
@@ -398,9 +613,27 @@ every item below; this list is what to look at when a vector fails.
 - [ ] Windows takes only the first type-1 and first type-2 structure, ignores type 4, and bounds
       every field read by the structure `length`.
 - [ ] `systemUuid` is uppercase hex, no hyphens, no byte swap; all-`00`/all-`FF` is absent.
+- [ ] `androidId` comes from `Settings.Secure.getString` and matches `^[0-9a-f]{1,16}$`; the literal
+      `"android_id"` never reaches the material.
 - [ ] Digest is SHA-256 over UTF-8 material, output as 64 lowercase hex characters.
-- [ ] The emitted device id is stamped `mbd2_` (or `mbd2n_` for the opt-in fallback).
-- [ ] A version difference is surfaced without claiming the license came from this machine.
+- [ ] The emitted device id is stamped `mbd2_` (`mbd2n_` for the opt-in fallback, `mbd2s_` for a
+      scoped identity).
+- [ ] A source tag the SDK does not define still **parses**, so the id can be compared literally
+      rather than rejected as "not a Moonbase id". A tag that happens to name a built-in of the
+      implementation language resolves the same way as any other unknown tag.
+- [ ] An id built from a scoped platform's parameters is stamped `mbd2s_` no matter which code path
+      collected them.
+
+**Review by hand:**
+
+- [ ] The platform tag follows the OS the process runs on. A Mac Catalyst build uses hardware
+      identity, not the scoped path.
+- [ ] The host-name fallback is not offered on `ios` or `android`.
+- [ ] A scoped id is never compared against one from another [scope](#what-the-scope-actually-is) —
+      in the SDK, on the server, and in analytics. Note that the last two live outside this
+      repository, so the vectors could not check them even in principle.
+- [ ] A version or source-tag difference is surfaced without claiming the license came from this
+      machine.
 
 ## Versioning
 

package/README.md

@@ -116,7 +116,9 @@ cross-SDK **[device fingerprint spec](./FINGERPRINT_SPEC.md)** (`moonbase:finger
 SHA-256 of stable native hardware identifiers, stamped with the spec version.
 
 ```
-mbd2_9f3c…            // 'mbd' + version + '_' + 64 lowercase hex characters
+mbd2_9f3c…            // 'mbd' + version + source tag + '_' + 64 lowercase hex characters
+mbd2n_9f3c…           // 'n': the opt-in host-name fallback (see below)
+mbd2s_9f3c…           // 's': an app-scoped id, which only the mobile SDKs produce
 ```
 
 Sources are SMBIOS on Windows, `IOPlatformUUID` on macOS, and `machine-id` plus world-readable DMI
@@ -125,6 +127,13 @@ passes the shipped [`fingerprint-vectors.json`](./fingerprint-vectors.json) comp
 given machine, so a license activated by one validates in the others. Adoption is per-SDK, so check
 the version of whichever SDK you are pairing with before relying on it.
 
+This package **parses** all three forms — including a tag introduced by a newer SDK, which it
+compares literally rather than rejecting — but its built-in readers only ever **produce** `mbd2_` or
+`mbd2n_`. Scoped ids come from iOS and Android, where the OS exposes no identifier an unrelated app
+can read; collecting them needs platform API no Node.js process can call, so that is the C++/.NET
+SDKs' job. A scoped id is stable only within one app scope and must never be compared with one from
+another, which is exactly what the `s` tag exists to announce.
+
 > Both files ship inside the package. If the links above do not resolve where you are reading this,
 > find them in `node_modules/@moonbase.sh/licensing/`.
 
@@ -157,7 +166,8 @@ catch (err) {
 The resolver throws `InsufficientDeviceIdentityError` rather than falling back to something weak, in
 two cases:
 
-- **Nothing readable.** A sandboxed process, or a platform with no defined parameters (Android, BSD).
+- **Nothing readable.** A sandboxed process; a platform the spec defines no parameters for (BSD, and
+  anything unrecognised); or Android, whose parameter this package cannot reach from Node.
 - **Only model-level values readable.** Vendor, product and board names are byte-identical across
   every unit of a product line, so fingerprinting them would let those machines validate one
   another's licenses. In practice: a Linux install with no `machine-id`, or a machine whose SMBIOS

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,
@@ -283,7 +285,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 +309,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 +330,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 +338,8 @@ var IDENTIFYING_PARAMS = /* @__PURE__ */ new Set([
   "machineId",
   "systemUuid",
   "baseboardSerialNumber",
+  "identifierForVendor",
+  "androidId",
   "deviceName"
 ]);
 var IDENTIFYING_PARAM_NAMES = Object.freeze([...IDENTIFYING_PARAMS]);
@@ -341,9 +364,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 +400,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 +413,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 +434,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 +576,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 +644,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 +891,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 +980,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 +1002,7 @@ var MoonbaseLicensing = class {
   defaultDeviceIdentityReader,
   fingerprintDeviceId,
   fingerprintDigest,
+  identitySource,
   parseDeviceIdStamp,
   parseIoregPlatformUuid,
   parseSmbiosParams,