@moonbase.sh/licensing 3.0.0 → 3.1.1

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

@@ -59,19 +59,67 @@ console.log('License stored locally')
 
 ## Validate on startup
 
-```ts
-const localLicense = await licensing.store.loadLocalLicense()
-
-if (localLicense) {
-  // Validate token signature + device binding locally
-  const locallyValidated = await licensing.validator.validateLicense(localLicense.token)
+Only delete the stored license when Moonbase says the license is gone. Deleting it on any error makes
+the user re-activate every time a check fails for a reason that has nothing to do with the license,
+such as opening the app offline.
 
-  // Re-validate against Moonbase (recommended for online activations)
-  const refreshed = await licensing.client.validateLicense(locallyValidated)
-  await licensing.store.storeLocalLicense(refreshed)
+```ts
+import type { License } from '@moonbase.sh/licensing'
+import { ActivationMethod, ErrorType, MoonbaseError } from '@moonbase.sh/licensing'
+
+// Moonbase says the license can no longer be used on this device. Anything
+// else, an ErrorType.ApiError or a network failure (which is not a
+// MoonbaseError), only means Moonbase could not be reached right now.
+const licenseGone = new Set<ErrorType | undefined>([
+  ErrorType.LicenseRevoked,
+  ErrorType.LicenseActivationRevoked,
+  ErrorType.LicenseExpired,
+  ErrorType.LicenseInvalid,
+  ErrorType.LicenseDeviceMismatch,
+])
+
+async function licenseOnStartup(): Promise<License | null> {
+  const localLicense = await licensing.store.loadLocalLicense()
+  if (!localLicense)
+    return null
+
+  if (localLicense.activationMethod === ActivationMethod.Online) {
+    try {
+      // Ask Moonbase first: it is how a revocation reaches the app, and how a
+      // token whose expiry has passed is refreshed after a renewal
+      const refreshed = await licensing.client.validateLicense(localLicense)
+      await licensing.store.storeLocalLicense(refreshed)
+      return refreshed
+    }
+    catch (err) {
+      if (err instanceof MoonbaseError && licenseGone.has(err.type)) {
+        await licensing.store.deleteLocalLicense()
+        return null // show your activation flow
+      }
+      // Moonbase could not be reached, so check the license locally instead
+    }
+  }
+
+  try {
+    // Signature, device binding and expiry, which needs no network
+    return await licensing.validator.validateLicense(localLicense.token)
+  }
+  catch (err) {
+    // Keep the stored token: only Moonbase can say the license is gone, and the
+    // next launch that reaches it can still refresh a token that has expired
+    if (err instanceof MoonbaseError)
+      return null // show your activation flow
+    throw err
+  }
 }
 ```
 
+A revoked license reports `ErrorType.LicenseRevoked`; a revoked device, whose license may still be
+active, reports `ErrorType.LicenseActivationRevoked`. To limit how long an app keeps running without
+reaching Moonbase, compare `license.validatedAt` with a limit of your choosing before returning the
+locally validated license. For `ErrorType.LicenseDeviceMismatch`, see [Device fingerprint](#device-fingerprint)
+first: after an SDK update, it can mean the same machine under an older fingerprint.
+
 ## Metadata, platform, and app version
 
 The SDK can report analytics with every activation, trial request, and validation. These are configured once on the `MoonbaseLicensing` config and sent automatically; there's no per-call parameter.
@@ -116,7 +164,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 +175,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 +214,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