From 57d7fa1f568f29c3bb269a9bb544f0482cba61bb Mon Sep 17 00:00:00 2001
From: Michael Heller <21163552+mdheller@users.noreply.github.com>
Date: Sun, 21 Jun 2026 22:23:42 -0400
Subject: [PATCH] Add DeviceIdentity example, validation, and registration
 endpoint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DeviceIdentity had a schema but no example, no validator coverage, and no API
operation — the missing peer to NLBootPlan/BootProofRecord in the boot/fleet
surface. Adds:
- examples/device_identity.json (a registered fleet device)
- DeviceIdentity to validate_nlboot_examples.py (make validate covers it)
- POST /v2/device-identities (upsertDeviceIdentity) in openapi.yaml, mirroring
  the nlboot-plans / boot-proof-records operations.
make validate passes.
---
 examples/device_identity.json     | 16 ++++++++++++++++
 openapi.yaml                      | 27 +++++++++++++++++++++++++++
 tools/validate_nlboot_examples.py |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 examples/device_identity.json

diff --git a/examples/device_identity.json b/examples/device_identity.json
new file mode 100644
index 0000000..5a1699b
--- /dev/null
+++ b/examples/device_identity.json
@@ -0,0 +1,16 @@
+{
+  "id": "urn:srcos:device-identity:rack-01",
+  "type": "DeviceIdentity",
+  "specVersion": "2.0.0",
+  "deviceName": "rack-01",
+  "platform": "linux",
+  "archClass": "x86_64",
+  "trustProfile": {
+    "trustLevel": "provisional",
+    "enrolledAt": "2026-06-22T00:00:00Z"
+  },
+  "ownerRef": "urn:srcos:user:operator-9",
+  "registeredAt": "2026-06-22T00:00:00Z",
+  "policyDecisionRefs": [],
+  "evidenceRefs": []
+}
diff --git a/openapi.yaml b/openapi.yaml
index 7de26d2..7fc63f4 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -608,6 +608,33 @@ paths:
           description: Request body is valid JSON but fails schema validation.
           content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
 
+  /v2/device-identities:
+    post:
+      operationId: upsertDeviceIdentity
+      summary: Upsert a DeviceIdentity
+      description: Registers or updates a fleet device identity (name, platform, trust profile, owner) that NLBoot plans target and boot proofs reference. Idempotent on `id`.
+      tags: [Boot]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/DeviceIdentity.json' }
+      responses:
+        '200':
+          description: DeviceIdentity registered or updated successfully.
+        '400':
+          description: Request body is malformed JSON.
+          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+        '401':
+          description: Missing or invalid authentication token.
+          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+        '403':
+          description: Authenticated subject is not permitted to register device identities.
+          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+
   /v2/apple-silicon-adapter-evidence:
     post:
       operationId: recordAppleSiliconAdapterEvidence
diff --git a/tools/validate_nlboot_examples.py b/tools/validate_nlboot_examples.py
index 4124435..43e1768 100644
--- a/tools/validate_nlboot_examples.py
+++ b/tools/validate_nlboot_examples.py
@@ -12,6 +12,7 @@
     (ROOT / "schemas" / "NLBootPlan.json", ROOT / "examples" / "nlboot_plan.json"),
     (ROOT / "schemas" / "ArtifactCacheRecord.json", ROOT / "examples" / "artifact_cache_record.json"),
     (ROOT / "schemas" / "BootProofRecord.json", ROOT / "examples" / "boot_proof_record.json"),
+    (ROOT / "schemas" / "DeviceIdentity.json", ROOT / "examples" / "device_identity.json"),
     (ROOT / "schemas" / "AppleSiliconAdapterEvidence.json", ROOT / "examples" / "apple_silicon_adapter_evidence.json"),
     # Release and build lifecycle objects
     (ROOT / "schemas" / "ReleaseSet.json", ROOT / "examples" / "release_set.json"),