@moonbase.sh/licensing 2.0.0 → 3.0.0

package/FINGERPRINT_SPEC.md

@@ -0,0 +1,414 @@
+# Moonbase Device Fingerprint Specification
+
+**Version:** `v2` · **Material prefix:** `moonbase:fingerprint:v2` · **Device id prefix:** `mbd2_`
+
+The language-neutral source of truth for how a Moonbase SDK (JavaScript, C++, .NET) computes a
+machine **device id**. Any two SDKs that conform compute the same id on a given machine, so a
+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.
+
+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
+disagrees with the vectors, **the vectors win**: they are what every SDK can actually execute.
+
+## Why it exists
+
+A license token carries a `sig` claim equal to the device id. Each SDK recomputes the device id
+locally and compares it to `sig` on every offline validation. If two SDKs compute it differently on
+the same machine, a license activated by one will not validate in the other. This spec removes that
+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.
+
+| Event | The device id must |
+|---|---|
+| Host name / computer rename | **not** change |
+| Locale, language or timezone change | **not** change |
+| IP address, DHCP lease or network change | **not** change |
+| BIOS / UEFI firmware update | **not** change |
+| Running as root/Administrator vs. unprivileged | **not** change |
+| RAM, GPU, disk or NIC added, removed or replaced | **not** change |
+| vCPU count changed on a VM | **not** change |
+| OS minor or major upgrade | **not** change |
+| App sandbox enabled/disabled; container restarted on the same host | **not** change |
+| OS **reinstall** | **may** change on Linux (see below); must not on macOS or Windows |
+| Motherboard replaced | **may** change |
+| Different physical machine | **must** change |
+| VM cloned to a new instance | **must** change on macOS and Windows; **cannot be guaranteed** on Linux (see below) |
+
+Three consequences are deliberate:
+
+- **Linux is tied to the OS installation, not the hardware.** Every per-unit DMI field
+  (`board_serial`, `product_serial`, `product_uuid`, `chassis_serial`) is mode `0400`, root-only. An
+  unprivileged process can read only model-level values, identical across every machine of the same
+  model. Linux therefore uses `machine-id`, which is world-readable and per-installation. The cost
+  is that a Linux OS reinstall requires re-activation.
+- **Firmware versions are never identity.** `bios_date`, `bios_version` and friends describe the
+  firmware, not the machine, and change on every BIOS update.
+- **A carelessly cloned Linux VM keeps its device id.** `machine-id(5)` requires an image intended
+  for reuse to ship with `/etc/machine-id` empty, so each instance generates its own on first boot.
+  When that is done, a clone gets a new id and this spec behaves correctly. When it is not, the
+  clone inherits a valid `machine-id`, every other Linux parameter is model-level, and the clone
+  fingerprints identically to its source, so a license copied with the disk keeps validating. An SDK
+  cannot detect this. The value that would distinguish the instances
+  (`/sys/class/dmi/id/product_uuid`, reassigned by the hypervisor) is root-only, and reading it
+  would break privilege-invariance for every user. Treat it as a known limit of unprivileged Linux
+  fingerprinting, not as something the algorithm can close.
+
+## Device id algorithm
+
+```
+digest    = lowercase_hex( SHA-256( UTF-8( material ) ) )
+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)).
+
+### Why the id is stamped
+
+The version once lived only inside the hashed material, which made it unrecoverable from the
+output. Stamping it means:
+
+- Supporting more than one version during a migration costs one hardware read, not one per version.
+  Parse the stamp on `sig`, compute that version, done.
+- An offline validator can tell an **out-of-date SDK** (binding is v3, it computes v2) from a
+  **stale binding** (binding is v1, it computes v2), and say something better than "wrong device".
+- The server, analytics and support can segment and reason about ids without a side channel.
+
+> **The stamp does not establish machine continuity.** A version difference says only which
+> algorithm created the binding. An older-version token copied from a different computer has exactly
+> the same version relationship as one created on this machine by an older SDK, so a validator
+> **must not** report an older stamp as proof that this is the same machine. Only recomputing the
+> historical id and finding a match establishes continuity, and when that succeeds validation passes
+> and never reaches an error. An SDK may surface the version difference to point at the right
+> remedy, but must phrase the remedy as conditional.
+
+**The stamp version and the material prefix version are always the same number.** Any change to
+collection rules, ordering, canonicalization or encoding that would alter the output for an
+unchanged machine must bump both.
+
+Assemble the material from the platform and an ordered list of identity parameters:
+
+1. Determine the **platform tag** (see below).
+2. Collect the ordered **identity parameters** for that platform, each a `(name, value)` pair.
+3. **Canonicalize** every value (see below) and **drop** any pair whose value is then empty, or
+   whose name is *identifying* and whose value is an [unprogrammed
+   placeholder](#identifying-parameters).
+4. If **no** pairs survive, or none of the survivors is an
+   [identifying parameter](#identifying-parameters), stop. This is an error, not a device id. See
+   [Insufficient identity](#insufficient-identity).
+5. If two surviving pairs share a name, stop. The grammar cannot express it, so this is a
+   collection bug.
+6. Assemble the material as lines **joined** by a single LF (`\n`, U+000A):
+
+   ```
+   moonbase:fingerprint:v2
+   platform=<platform-tag>
+   <name>=<value>
+   <name>=<value>
+   ...
+   ```
+
+   > The LF is a **separator, not a terminator**. The material does **not** end with a newline.
+   > Appending `"\n"` after each line is the single most likely way to produce an SDK that looks
+   > correct and agrees with nothing. The vectors check this explicitly.
+
+7. UTF-8 encode the material, SHA-256 it, lowercase-hex encode the 32-byte digest, and prefix the
+   stamp.
+
+### Canonicalizing values
+
+Apply these steps to every value, in this order:
+
+1. **Normalize** to Unicode NFC.
+2. **Drop** every character outside printable ASCII, keeping only U+0020 to U+007E.
+3. **Truncate** to at most 128 characters.
+4. **Trim** spaces from both ends.
+
+Interior spaces are preserved. Nothing else is altered: no case folding, no reordering.
+
+Step 2 does more work than it looks:
+
+- It makes the material grammar unambiguous. A value can no longer contain an LF, so it cannot forge
+  an extra `name=value` line, and two different parameter sets can never assemble into the same
+  material.
+- It makes the decoding of raw firmware strings irrelevant. SMBIOS strings are nominally ASCII, but
+  OEMs ship Latin-1 and worse. An SDK decoding them as Latin-1, one decoding as UTF-8 and one
+  keeping raw bytes would otherwise disagree on any non-ASCII byte. Every byte they disagree about
+  is discarded, so they cannot.
+- It absorbs the trailing `\n` that sysfs reads and command output carry.
+
+### Identifying parameters
+
+Most of what a platform collects is **model-level**: vendor, product, board and family names are
+byte-identical across every unit of a product line. A material built only from those would give
+every machine of that model the same device id, and each would validate the others' licenses.
+
+Exactly these parameters count as **identifying**, describing the individual machine:
+
+| Parameter | Platform |
+|---|---|
+| `ioPlatformUuid` | macOS |
+| `machineId` | Linux |
+| `systemUuid` | Windows |
+| `baseboardSerialNumber` | Windows |
+| `deviceName` | the opt-in host-name fallback only |
+
+At least one must survive canonicalization, or the result is
+[insufficient identity](#insufficient-identity). This is not a rare path. A Linux install with no
+`machine-id`, or a cloned VM whose SMBIOS carries an unset UUID and a blank baseboard serial, both
+land here and must be refused rather than fingerprinted as their model.
+
+`deviceName` counts only because it is the sole parameter of the host-name fallback. Its weakness is
+signalled by the `mbd2n_` stamp instead.
+
+**Unprogrammed placeholders.** An identifying value that is really OEM filler is treated as
+**absent**, for the same reason an all-`FF` SMBIOS UUID is: it is a constant shared by the whole
+product line. Compared case-insensitively against the canonical value:
+
+`to be filled by o.e.m.`, `to be filled by oem`, `default string`, `system serial number`,
+`base board serial number`, `chassis serial number`, `not specified`, `not applicable`,
+`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`).
+
+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.
+
+### Platform tags
+
+| OS family | Tag |
+|---|---|
+| macOS | `mac` |
+| Windows | `windows` |
+| Linux | `linux` |
+| Android | `android` |
+| FreeBSD / OpenBSD / NetBSD | `bsd` |
+| anything else | `unknown` |
+
+## Identity parameters per platform
+
+Parameters **must** appear in the order listed. Reads are best-effort: a missing or unreadable
+source yields an empty value, which step 3 then drops. A partially-available machine still hashes
+deterministically, and conforming SDKs agree because they apply the same collection rules.
+
+### macOS (`mac`)
+
+| Order | Name | Identifying | Source |
+|---|---|---|---|
+| 1 | `ioPlatformUuid` | ✅ | IOKit `IOPlatformUUID` of `IOPlatformExpertDevice`, with all `-` removed and **uppercased**. Read via IOKit, or `ioreg -rd1 -c IOPlatformExpertDevice` and match `"IOPlatformUUID" = "…"`. |
+
+macOS collects a single parameter, so a read either succeeds or yields insufficient identity.
+
+### Linux (`linux`)
+
+All five sources are world-readable files, so the result does not depend on privilege, on any
+installed CLI, or on the locale. No subprocess is spawned.
+
+| Order | Name | Identifying | Source |
+|---|---|---|---|
+| 1 | `machineId` | ✅ | the first of `/etc/machine-id` and `/var/lib/dbus/machine-id` holding a **valid** id (see below) |
+| 2 | `sysVendor` | | `/sys/class/dmi/id/sys_vendor` |
+| 3 | `productName` | | `/sys/class/dmi/id/product_name` |
+| 4 | `boardVendor` | | `/sys/class/dmi/id/board_vendor` |
+| 5 | `boardName` | | `/sys/class/dmi/id/board_name` |
+
+A source counts only if its canonical value matches `^[0-9a-f]{32}$`, the format `machine-id(5)`
+defines, **and** is not an [unprogrammed placeholder](#identifying-parameters). Apply the same
+placeholder rule here as canonicalization does. A check that admits a value canonicalization will
+later discard (an all-`f` id passes a naive hex test) strands the remaining sources.
+
+**Validate each source before selecting it**, rather than taking the first non-empty one.
+`/etc/machine-id` legitimately holds the literal marker `uninitialized` in an initrd or a golden
+image awaiting first boot, and every machine deployed from that image reads the same marker.
+Treating it as an id would give them all one device id, and would also stop the fall-through to a
+D-Bus id that may be perfectly valid.
+
+`machineId` is the only per-machine value here; the DMI fields are model-level context. On a board
+with no DMI at all (many ARM SBCs) only `machineId` survives, which is correct and still unique.
+
+Because it is the only identifying parameter, **a Linux machine with no readable `machine-id` has no
+device identity** and must be refused. Every remaining field is shared by every unit of the model,
+so fingerprinting them would let those machines validate one another's licenses. This is reachable:
+non-systemd installs, minimal containers, and images shipped with an empty `/etc/machine-id`.
+
+> Do **not** add `board_serial`, `product_uuid` or any other `0400` file: the id would then depend
+> on whether the process runs as root. Do **not** add `bios_*`: those change on firmware update. Do
+> **not** parse `lscpu`: its labels are translated, so the id would depend on `LANG`, and its values
+> are model-level anyway.
+
+### Windows (`windows`)
+
+Read the raw SMBIOS structure table, via `GetSystemFirmwareTable('RSMB')` (P/Invoke on .NET, native
+on C++) or WMI `root\wmi` → `MSSmBios_RawSMBiosTables.SMBiosData`.
+
+> If you read via `GetSystemFirmwareTable('RSMB')`, skip the leading 8-byte `RawSMBIOSData` header
+> (`Used20CallingMethod`, 3 version bytes, `DWORD Length`); parsing starts at the first structure.
+> WMI's `SMBiosData` already excludes that header.
+
+Walk the structures and take the **first** structure of type 1 and the **first** of type 2. Later
+structures of the same type are ignored.
+
+| Type | Order | Name | Identifying | Field offset within the structure |
+|---|---|---|---|---|
+| 1 System | 1 | `systemManufacturer` | | `0x04` (string) |
+| | 2 | `systemProductName` | | `0x05` (string) |
+| | 3 | `systemUuid` | ✅ | `0x08` (16 raw bytes) |
+| 2 Baseboard | 4 | `baseboardManufacturer` | | `0x04` (string) |
+| | 5 | `baseboardProduct` | | `0x05` (string) |
+| | 6 | `baseboardSerialNumber` | ✅ | `0x07` (string) |
+
+At least one of `systemUuid` and `baseboardSerialNumber` must survive, or the machine has no device
+identity and must be refused. **Both being unusable is the common case on cloned VM images and on
+consumer boards**: an unset (all-`00`/all-`FF`) UUID alongside a baseboard serial that is blank or an
+OEM filler string like `To be filled by O.E.M.` Without this rule every such machine would
+fingerprint as its model and share a binding.
+
+Type 4 (Processor) is deliberately **not** collected. Its values are model-level rather than
+per-machine, and the number of type-4 structures tracks the CPU socket / vCPU count, so collecting
+them would change the device id every time a VM is resized.
+
+SMBIOS structure walking:
+
+- Header: `type` (byte @0x00), `length` (byte @0x01, the size of the **formatted** area including
+  the header), `handle` (word @0x02).
+- The **string table** immediately follows the formatted area: NUL-terminated strings ending in a
+  double-NUL. A structure with no strings is just the double-NUL.
+- A **string field** in the formatted area holds a **1-based index** into that string table. Index
+  `0`, or an index past the end, means "no string" and yields an empty value.
+- **Bound every field read by the structure's own `length`**, not by the size of the table. Older
+  (SMBIOS 2.x) structures are shorter than the current layout, and reading past the formatted area
+  silently picks up bytes from the string pool and resolves a garbage index.
+- `systemUuid` is the 16 bytes at offset `0x08` formatted as **uppercase hexadecimal, no hyphens, no
+  byte reordering**: the raw bytes in order, exactly 32 hex characters. Do **not** apply the
+  SMBIOS-canonical little-endian swap of the first three UUID fields. The value will therefore not
+  match what `dmidecode`, `wmic csproduct get uuid` or `Win32_ComputerSystemProduct` display. That is
+  intentional, and an SDK reading the UUID through WMI must undo the swap.
+- 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`)
+
+No identity parameters are defined. These platforms always resolve to
+[insufficient identity](#insufficient-identity).
+
+## Insufficient identity
+
+An SDK **must** raise an error when no parameter survives canonicalization, or when none of the
+survivors is an [identifying parameter](#identifying-parameters). It must **not** hash the platform
+line alone, **not** hash a model-only parameter set, and **not** silently substitute the host name.
+
+Each of those is well-defined but catastrophic in the same way: it hands a whole class of machines
+(every machine on a platform, or every unit of a model) the *same* device id, and a license bound to
+that id then validates on all of them. Substituting the host name is nearly as bad, being
+user-renameable, duplicated across imaged fleets, and regenerated on every container start.
+
+An SDK **may** offer an explicit, opt-in host-name fallback for platforms with no defined
+parameters. The material is then the single parameter `deviceName=<host name>`, and the id **must**
+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.
+
+## Device name
+
+A human-readable label sent alongside the device id at activation. It is **not** part of the
+material (except in the opt-in fallback above), so it can change freely without invalidating a
+license.
+
+| Platform | Source |
+|---|---|
+| macOS | host name, with a trailing `.local` removed (case-insensitive) |
+| other | host name |
+
+## Worked examples
+
+Reproduced by [`fingerprint-vectors.json`](./fingerprint-vectors.json), which contains these and
+many more. Materials are shown with literal newlines and, to repeat, **no trailing newline**.
+
+**macOS:**
+
+```
+moonbase:fingerprint:v2
+platform=mac
+ioPlatformUuid=0123456789ABCDEF0123456789ABCDEF
+```
+→ `mbd2_b465194056ff7721bf549799b4532bfca0bc72fffc0f6969c77c46d6b8e28e32`
+
+**Linux:**
+
+```
+moonbase:fingerprint:v2
+platform=linux
+machineId=b08dfa6083e7567a1921a715000001fb
+sysVendor=LENOVO
+productName=20HRCTO1WW
+boardVendor=LENOVO
+boardName=20HRCTO1WW
+```
+→ `mbd2_ba16d78604f90c6c8b00dc1065a70c866884fadfa818ed2db83b2bfe0dc94933`
+
+**Windows:**
+
+```
+moonbase:fingerprint:v2
+platform=windows
+systemManufacturer=ACME
+systemProductName=Server 9000
+systemUuid=0123456789ABCDEF0123456789ABCDEF
+baseboardManufacturer=ACME
+baseboardProduct=MB-1
+baseboardSerialNumber=BSN-42
+```
+→ `mbd2_fadd75457e44f669e9865caff122b4706a4501089ac9e73b8735139bf57676ad`
+
+**Opt-in host-name fallback** (note the `n`):
+
+```
+moonbase:fingerprint:v2
+platform=unknown
+deviceName=PC-1
+```
+→ `mbd2n_493978eb157552e60a13694bd6861b2a82d0dba2746431a5f7921951ed460045`
+
+## 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.
+
+- [ ] Material prefix is exactly `moonbase:fingerprint:v2`.
+- [ ] Lines are **joined** with a single LF, and the material has **no trailing newline**.
+- [ ] Values are canonicalized NFC → printable-ASCII-only → capped at 128 → space-trimmed, in that
+      order; empty values are dropped.
+- [ ] Identifying parameters holding an unprogrammed placeholder are dropped; descriptive ones are
+      not.
+- [ ] An empty surviving parameter set raises an error rather than producing a digest.
+- [ ] A surviving set with no identifying parameter raises an error rather than fingerprinting the
+      model.
+- [ ] Duplicate parameter names raise an error.
+- [ ] Per-platform params are collected with the exact names and order above.
+- [ ] Linux spawns no subprocess and reads no root-only file, and validates each `machine-id` source
+      against `^[0-9a-f]{32}$` and the placeholder rule before selecting it.
+- [ ] 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.
+- [ ] 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.
+
+## Versioning
+
+The material prefix and the device id stamp both carry the version, and they always match. Any
+change to collection rules, ordering, canonicalization or encoding that would alter output for an
+unchanged machine **must** bump both (to `moonbase:fingerprint:v3` and `mbd3_`).
+
+Because the version is recoverable from the id, an SDK can validate against several versions during
+a migration while emitting only one. Parse the stamp on the `sig` claim and compute that version. If
+the SDK no longer supports it, say the license needs re-activating rather than reporting the machine
+as wrong.

package/README.md

@@ -74,14 +74,14 @@ if (localLicense) {
 
 ## 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.
+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.
 
 - `appVersion` and `platform` are first-class fields and sent as plain query params. `metadata` is for arbitrary customer-defined keys, sent as `meta[key]=value`.
 - `platform` auto-detects from `process.platform` (`darwin` → `Mac`, `win32` → `Windows`, `linux` → `Linux`). Set it explicitly to override, or pass `null` to suppress.
-- All three are sent on `requestActivation`, `requestTrial`, and `validateLicense` — never on `revokeLicense`.
+- All three are sent on `requestActivation`, `requestTrial`, and `validateLicense`, never on `revokeLicense`.
 - `metadata` accepts string keys and string values only; empty values are dropped client-side.
 - Server-side, the metadata on the activation is **replaced on every call** (not merged) and surfaced in `LicenseActivatedEvent` / `LicenseValidatedEvent` webhooks.
-- The config object is re-read on every call — mutate `metadata` between calls (e.g. to rotate a session id) and the next request picks it up.
+- The config object is re-read on every call, so mutating `metadata` between calls (e.g. to rotate a session id) means the next request picks it up.
 - Keep payloads small; query-string length limits apply.
 
 ## Revoke a license activation
@@ -108,9 +108,136 @@ Read and validate raw license bytes (for example from a file):
 ```ts
 const license = await licensing.readRawLicense(rawLicenseBuffer)
 ```
+## Device fingerprint
 
-## Custom stores and device resolvers
+Every license is bound to the machine via a device id, stored in the token's `sig` claim and
+re-checked on each local validation. The default `MoonbaseDeviceIdResolver` computes it from the
+cross-SDK **[device fingerprint spec](./FINGERPRINT_SPEC.md)** (`moonbase:fingerprint:v2`): a
+SHA-256 of stable native hardware identifiers, stamped with the spec version.
+
+```
+mbd2_9f3c…            // 'mbd' + version + '_' + 64 lowercase hex characters
+```
+
+Sources are SMBIOS on Windows, `IOPlatformUUID` on macOS, and `machine-id` plus world-readable DMI
+on Linux. The algorithm is language-neutral by design: any Moonbase SDK that implements the spec and
+passes the shipped [`fingerprint-vectors.json`](./fingerprint-vectors.json) computes the same id on a
+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.
+
+> 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/`.
+
+The id survives a rename, a locale change, a firmware update, a vCPU resize, and running with or
+without elevated privileges. The spec's **stability contract** is the definitive list. Read it
+before shipping, along with the two Linux exceptions, which exist because every per-unit hardware
+serial is root-only there and the id is tied to the OS installation rather than the hardware:
+
+- A Linux **OS reinstall** requires re-activation.
+- A Linux **VM cloned without clearing `/etc/machine-id`** keeps its device id, so a license copied
+  with the disk keeps validating. `machine-id(5)` requires reusable images to ship that file empty;
+  when they do, clones behave correctly. The SDK cannot detect a badly-prepared image, because the
+  value that would distinguish the instances is root-only.
+
+Because the version is part of the id, a mismatch is diagnosable. `validateLicense` throws
+`ErrorType.LicenseDeviceMismatch` either way, and the message says which case you are in:
+
+```ts
+try {
+  await licensing.validator.validateLicense(token)
+}
+catch (err) {
+  if (err.type === ErrorType.LicenseDeviceMismatch)
+    console.error(err.message) // 'not for this device', plus any version difference
+}
+```
+
+### When there is no hardware identity
+
+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).
+- **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
+  carries an unset UUID *and* a blank or filler baseboard serial, the usual shape of a cloned VM
+  image.
+
+Opt in explicitly if a weaker id beats none. Those ids are stamped `mbd2n_` so the server can tell
+them apart:
+
+```ts
+const deviceIdResolver = new MoonbaseDeviceIdResolver({ fallback: 'deviceName' })
+```
 
-You can inject your own `ILicenseStore` and `IDeviceIdResolver` implementations.
+### Diagnostics and parity checks
+
+`describeDevice()` returns the id, spec version, platform and the *names* of the parameters that
+contributed. It is safe to log or attach to a support ticket, and returns a fresh copy each call so
+editing it cannot disturb the binding.
+
+Parameter values are never exposed there, and neither are per-parameter hashes. They are hardware
+serial numbers, and an unsalted per-value digest is no safer to publish than the value, since
+low-entropy values such as host names or sequential serials fall to a dictionary. Which parameters
+contributed is the useful diagnostic; what they read is not.
+
+The device id itself is a one-way hash of all of them together, so it discloses no individual
+serial. It is, however, **derived identically for every Moonbase-powered product**. The material
+contains no product- or account-specific input, so the same machine yields the same device id
+everywhere, and merchants receive that string through the integration API and webhooks. Treat it as
+a stable cross-vendor machine identifier. That is more than `machine-id(5)` intends, which asks that
+the Linux machine id only leave the host through an *application-specific keyed* derivation. If that
+matters for your deployment, supply a custom `IDeviceIdResolver` that mixes in a key of your own.
+
+The lower-level `buildFingerprintMaterial`, `fingerprintDigest`, `fingerprintDeviceId` and
+`parseDeviceIdStamp` helpers are exported so you can verify cross-SDK parity against the vector
+file.
+
+## Migrating from v2.x
+
+Device ids computed by v2.x are not compatible with the spec, so **by default every device must
+re-activate once** after you upgrade. That is not free: a new device id consumes a fresh activation
+seat (the old one is not reclaimed) and resets any device-scoped trial. On a license with few seats,
+a fleet-wide upgrade can exhaust them immediately.
+
+Three options, in increasing order of effort:
+
+**1. Let devices re-activate (default).** Simplest, and the id is correct from then on. Catch
+`ErrorType.LicenseDeviceMismatch` and call `requestActivation()`. Best when seats are generous or the
+install base is small.
+
+**2. Accept the old id while binding the new one (recommended for existing fleets).**
+`MigratingDeviceIdResolver` keeps recognising ids this device was previously bound to, without ever
+issuing one:
+
+```ts
+import { LegacyDeviceIdResolver, MigratingDeviceIdResolver, MoonbaseDeviceIdResolver } from '@moonbase.sh/licensing'
+
+const licensing = new MoonbaseLicensing({
+  // …
+  deviceIdResolver: new MigratingDeviceIdResolver(
+    new MoonbaseDeviceIdResolver(), // always what a new activation binds
+    new LegacyDeviceIdResolver(), // additionally accepted during validation
+  ),
+})
+```
+
+Existing licenses keep validating untouched, while anything newly activated binds the current
+fingerprint. The fleet migrates as devices naturally re-activate, with no flag day and no seat
+churn. The legacy id is computed lazily, only when the fast comparison fails, and then memoized, so
+apps on the happy path pay nothing. Drop the wrapper in a later release to finish the migration.
+
+**3. Stay on the old id.** Pin `deviceIdResolver: new LegacyDeviceIdResolver()`. Nothing changes, but
+you keep the old algorithm's defects (the machine name is part of the id, so renaming a computer
+invalidates its license) and get no cross-SDK compatibility. Use this only as a short-term hold.
+
+> Options 1 and 2 both recompute every accepted id from the machine's own hardware on each call.
+> Nothing about a device binding is ever read from disk, so widening what a validator accepts does
+> not widen what an attacker can assert.
+
+## Custom stores and device resolvers
 
-Note: the current configuration property name for custom device resolver is `deivceIdResolver`.
+You can inject your own `ILicenseStore` and `IDeviceIdResolver` implementations via the
+`licenseStore` and `deviceIdResolver` configuration options. A custom resolver's id is compared
+literally, so it does not need to follow the `mbd2_` stamp format.