Add stable opt-in per-prefix identity provisioning

docs/PLATFORM_IDENTITY.md

@@ -1,9 +1,9 @@
 # Explicit platform identity overrides
 
 By default, Darling keeps the existing host-derived UUID and `DARLING-` serial.
-No override file is generated by installation or launch. This tool imports
-values supplied by the user; it does not generate Apple serials or replace OS,
-CPU, GPU, or security metadata.
+No override file is generated by installation or launch. Import mode uses values supplied by the user. Explicit `--provision` mode can
+generate synthetic identifiers; it does not issue authentic Apple identities
+or change CPU, GPU, or security metadata.
 
 Preview an OpenCore `config.plist`, a flat GenSMBIOS JSON file, or an existing
 `darling-smbios.conf` without changing the selected prefix:
@@ -42,6 +42,7 @@ Supported properties:
 | Property | Configuration value | IOKit value |
 |---|---|---|
 | `IOPlatformSerialNumber` | Printable ASCII string, 1–64 characters | NSString |
+| `provisioning_UDID` | UUID string matching `IOPlatformUUID` | NSString |
 | `IOPlatformUUID` | Nonzero UUID; normalized to uppercase | NSString |
 | `manufacturer`, `model`, `product-name`, `board-id` | Printable ASCII string, 1–128 characters | NUL-terminated NSData |
 | `mlb-serial-number` | Printable ASCII string, 1–64 characters | NUL-terminated NSData |
@@ -71,3 +72,65 @@ first previous configuration is kept as
 an older `.conf` never edits that source. Symlinks escaping the prefix are
 rejected. To restore the original defaults, remove the override file while the
 prefix is stopped, then restart it.
+
+## Opt-in provisioning
+
+Preview a fresh or repaired identity without writing anything:
+
+```sh
+python3 tools/configure-darling-platform.py --prefix /absolute/prefix --provision
+```
+
+Stop the prefix, then save the identity and prefix metadata:
+
+```sh
+DPREFIX=/absolute/prefix python3 build/runtime/tools/stop-darling-runtime.py
+python3 tools/configure-darling-platform.py --prefix /absolute/prefix --provision --write
+```
+
+Launch Darling normally afterwards. This requires the updated iokitd from this
+PR; the config tool alone cannot update an older running daemon. Provisioning
+is never called automatically by installation or launch.
+
+Missing serials use 12 characters and missing MLBs use 17 characters, sampled
+with Python's `secrets` module from `0123456789ABCDEFGHJKLMNPQRSTUVWXYZ` (Base-34).
+These are synthetic strings, with no Apple model, factory, date or checksum
+validation, allocation, or guarantee of acceptance by Apple services. Missing
+UUIDs use RFC4122 v4; `system-id` contains the UUID's 16 little-endian bytes.
+For this project `provisioning_UDID` is the uppercase platform UUID alias, not
+a separate Apple provisioning credential or a claim about hardware UDIDs.
+
+Missing ROMs default to six random bytes with the local/unicast bits set. You
+can explicitly supply a three-byte OUI using `--rom-oui AA:BB:CC` (replace the
+example with your chosen unicast OUI). It only affects a missing ROM. An OUI
+does not make a generated identity Apple-issued.
+
+Provisioning replaces the known shared serial `C02ZL0GVMD6N` and UUID
+`6F3B2A1E-8C4D-4E5F-9A7B-1D2C3E4F5A6B`, along with the latter's derived fields.
+It preserves other existing custom values, including imported serials and UUIDs
+that do not follow the generated formats. A standalone custom `system-id` is
+preserved by deriving its UUID instead of generating a different one. Model,
+board and manufacturer values are only set when supplied by the user.
+
+The command reads an existing prefix `darling-smbios.conf` for migration, then
+applies the canonical plist, an explicit import, and `--set` values in that
+order. It writes:
+
+- `private/etc/darling-platform.plist`: canonical runtime overrides.
+- `private/etc/darling-smbios.conf`: matching shell-quoted `SMBIOS_*` values,
+  including `SMBIOS_PROVISIONING_UDID`; unrelated legacy settings are not exported.
+- `System/Library/CoreServices/SystemVersion.plist`: an exact copy of the selected
+  runtime's metadata, not a fabricated macOS release. The runtime root defaults
+  to the saved SDK path or `/usr/local/libexec/darling`; override with
+  `--runtime-root /path/to/runtime`.
+
+A valid runtime version file is required. The command checks all destinations
+before changing identity files, rejects live prefixes and escaping symlinks,
+backs up each previous file once with `.before-platform-change`, and replaces
+each file atomically. The set of three files is not a single transaction: the
+canonical identity is saved first so rerunning after interruption completes
+provisioning with the same identity. Concurrent CLI writers serialize through
+a per-prefix lock. Repeated writes preserve identifiers and unchanged files.
+Previewing a fresh identity generates a sample; only `--write` makes it stable.
+To restore host-derived defaults after provisioning, remove both identity files
+while stopped, so a later provisioning run cannot reimport the legacy copy.

docs/reviews/pr41-deferred-implementation.md

@@ -53,7 +53,8 @@ above the 32-bit range should use the named 64-bit API.
 [Platform identity configuration](../PLATFORM_IDENTITY.md) documents the schema,
 OpenCore/GenSMBIOS/legacy imports, startup snapshot, defaults, and rollback.
 Neither installation nor launch generates an override file. Existing host-based
-identifiers remain stable unless the user explicitly supplies replacements.
+identifiers remain stable unless the user explicitly supplies replacements or
+requests synthetic per-prefix provisioning.
 
 ## Validation
 
@@ -96,3 +97,12 @@ darling shell /Volumes/SystemRoot/ABSOLUTE_PROJECT_PATH/build/riot-cpu-frequency
 Local validation also ran the fd helper inside Darling and used an isolated
 kernel override for the frequency probe. The configured production runtime was
 not replaced, no real identity was changed, and no match capture is required.
+
+
+Opt-in provisioning now fills missing synthetic serial/MLB, UUID, system-id,
+provisioning UUID alias and ROM fields. It repairs the two known shared defaults
+while retaining custom values, synchronizes the canonical and legacy config,
+and copies actual runtime SystemVersion metadata. Disposable-prefix tests cover
+concurrent writers, idempotency, migration, backups, live-prefix refusal, and
+preflight failures. The registry probe validates all ten allowed properties.
+See [platform identity usage](../PLATFORM_IDENTITY.md#opt-in-provisioning).