feat(devices): add remote platform erase support

[nmgaston]

NOTE: Requires real AMT 16.0+ hardware with RPE BIOS support for end-to-end testing.

Related PRs

• go-wsman-messages: feat: add RPE parameter types, sizes, and validation maps go-wsman-messages#665 (required — adds RPE TLV parameter types and NewUint32Parameter)
• sample-web-ui: feat(devices): add remote platform erase support sample-web-ui#3206 (frontend changes for RPE UI)

Description

Adds support for Intel Remote Platform Erase (RPE), a CSME 16.0+ feature that allows remote administrators to securely erase platform storage components (SSDs, TPM, BIOS NVM, etc.) on the next system boot.

What's New

API Endpoints

Method	Path	Description
GET	/api/v1/amt/boot/remoteErase/:guid	Returns BootCapabilities indicating which erase components the device BIOS supports (decoded from AMT_BootCapabilities.PlatformErase)
POST	/api/v1/amt/boot/remoteErase/:guid	Arms and triggers RPE on the next boot via a RemoteEraseRequest body specifying which components to erase

GET Response — BootCapabilities

{
  "secureEraseAllSSDs": true,
  "tpmClear": true,
  "restoreBIOSToEOM": true,
  "unconfigureCSME": true
}

Each field is decoded from the AMT_BootCapabilities.PlatformErase bitmask:

Field	Bitmask bit	Value
secureEraseAllSSDs	Bit 2	0x04
tpmClear	Bit 6	0x40
restoreBIOSToEOM	Bit 26	0x4000000 — BIOS Reload of Golden Configuration
unconfigureCSME	Any RPE bit set	PlatformErase != 0

POST Request — RemoteEraseRequest

{
  "secureEraseAllSSDs": false,
  "tpmClear": false,
  "restoreBIOSToEOM": false,
  "unconfigureCSME": false
}

RPE Trigger Flow (SetRemoteEraseOptions)

1. Reset boot service to idle (32768) — CIM_BootService.RequestStateChange(32768). Non-fatal; some firmware versions return ActionNotSupported here.
2. Pre-latch PlatformErase=true — sparse PUT AMT_BootSettingData. Non-fatal; the full PUT in step 4 also sets this flag, so erase can still succeed if this fails.
3. GET AMT_BootSettingData — read current state and verify RPEEnabled=true. Returns NotSupported error to the caller if the flag is absent.
4. (CSME-only path) CIM_BootConfigSetting.ChangeBootOrder("") — clears any active boot source override before setting CSME reset flags (equivalent to ClearBootOptions in the Intel AMT C# SDK). Only called when no hardware TLV targets are present (tlvMask == 0); clearing the boot order when hardware targets are also present causes undefined BIOS behavior.
5. CIM_BootService.RequestStateChange(32770) — switch firmware to RPE mode. Required when the boot service is in OCR mode (32769); omitting it causes ActionNotSupported.
6. PUT AMT_BootSettingData with:
   • PlatformErase=true (when hardware TLV targets are present)
   • ConfigurationDataReset=true (when unconfigureCSME was requested)
   • UefiBootParametersArray=<TLV> (when hardware TLV targets are present)
   • On PUT failure: performs a follow-up GET to check whether PlatformErase latched from the pre-latch step; aborts if it did not.
7. CIM_BootService.SetBootConfigRole — activate the boot configuration.
8. RequestPowerStateChange(PowerCycleOffHard) — full S5→S0 power cycle to execute erase on next boot.

TLV Encoding (UefiBootParametersArray)

When hardware targets are present the tlvMask (request bitmask with rpeCSMEBit stripped) is encoded as a single TLV entry and base64-encoded into UefiBootParametersArray:

Format (12 bytes, all fields little-endian):
  [vendor:2]  [typeID:2]  [length:4]  [value:4]
  0x8086       0x0001      0x00000004  <tlvMask uint32>

CIM_BootService.EnabledState Constants

Value	Meaning
32768	OCR disabled, RPE disabled
32769	OCR enabled, RPE disabled
32770	OCR disabled, RPE enabled
32771	OCR enabled, RPE enabled

SetFeatures computes the required state via ocrBootState(ocr, rpe), and setRPE runs before the boot service state change to avoid the OCR state blocking the RPE PUT.

DTO / Feature Surface

Features and FeaturesRequest DTOs (v1 + v2) updated with:

Field	DTO	Description
rpe	Features (v1 + v2), FeaturesRequest (v1)	Whether RPE is currently active in firmware (EnabledState is 32770 or 32771)
rpeSupported	Features (v1 + v2)	Whether device BIOS supports RPE (Bit 0 of PlatformErase capabilities, 0x01)

Testing

• Unit tests added for GetRemoteEraseCapabilities and SetRemoteEraseOptions use-case functions and HTTP controller handlers
• SetFeatures tests extended to cover RPE + OCR state combinations
• Unit tests added for buildRPETLVParams covering individual hardware targets, combined masks, and CSME bit stripping
• Verified on real AMT 18.1 hardware

Notes

• 0x10000 (rpeCSMEBit) is a UI-level sentinel for "Unconfigure Intel CSME Firmware". It is not passed as a TLV device-bitmask bit. When set in the request it sets ConfigurationDataReset=true in the PUT and is stripped from tlvMask. PlatformErase and ConfigurationDataReset are independent flags and are never both set from the same bit.
• CSME unconfigure (unconfigureCSME) must be requested alone — it cannot be combined with hardware TLV targets (TPM, SSD, BIOS Reload) in one call. The UI enforces this; the backend additionally guards ChangeBootOrder from firing when tlvMask != 0 to prevent silently poisoning hardware targets if the API is called directly with a combined mask.
• UefiBootParametersArray must be non-empty when PlatformErase=true — the firmware returns InvalidRepresentation if the element is absent or empty. The TLV device bitmask (ParameterTypeID=1) is mandatory per the Intel RPE spec.
• PowerCycleOffHard (S5→S0) is required for erase execution; MasterBusReset (warm reset) keeps ME power rails energised so the BIOS never executes the CSME/platform erase.
• RequestStateChange(32770) must be called before the PUT when the boot service is in OCR mode (32769); omitting it causes ActionNotSupported.
• Devices where AMT_BootCapabilities.PlatformErase == 0 return a validation error rather than attempting the operation.

[codecov]

Codecov Report

❌ Patch coverage is 75.18248% with 68 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.14%. Comparing base (9671bd3) to head (f49203a).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/mocks/wsv1_mocks.go	0.00%	26 Missing ⚠️
internal/mocks/devicemanagement_mocks.go	0.00%	21 Missing ⚠️
internal/mocks/wsman_mocks.go	0.00%	17 Missing ⚠️
internal/controller/openapi/devicemanagement.go	85.18%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #846      +/-   ##
==========================================
+ Coverage   43.44%   47.14%   +3.70%     
==========================================
  Files         143      145       +2     
  Lines       13621    13811     +190     
==========================================
+ Hits         5917     6511     +594     
+ Misses       7143     6728     -415     
- Partials      561      572      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[rsdmike]

Thanks @nmgaston for doing this. @graikhel-intel and i have taken some time to think through and go through this. Here is our feedback:

1. Simplify AMT features request/response to just include rpeSupported and rpe:

{
    "redirection": true,
    "KVM": true,
    "SOL": true,
    "IDER": true,
    "optInState": 0,
    "userConsent": "none",
    "kvmAvailable": true,
    "ocr": false,
    "httpsBootSupported": true,
    "winREBootSupported": true,
    "localPBABootSupported": true,
    "rpe": true,
    "rpeSupported": true,
<remove>
    "rpeCaps": 100728925,
    "rpeSecureErase": true,
    "rpeTPMClear": true,
    "rpeClearBIOSNVM": true,
    "rpeBIOSReload": true
</remove>
}

Once this is done, can update the UI on the General AMT Info screen change RPE into a checkbox which will enable/disable rpe and grey it out/disable if rpe is not supported.

2. Currently you have GET: boot/capabilities/:guid (where is this used?) , POST: boot/rpe/:guid, and POST: remoteErase/:guid endpoints added. Consolidate this to GET boot/remoteErase/:guid -- which will fetch the supported capabilities
   and POST boot/remoteErase/:guid which will perform the desired action

 {
  "secureEraseAllSSDs": true,
  "tpmClear": true,
  "restoreBIOSToEOM": true,
  "unconfigureCSME": true
}

Note important removal of any mask representation of features. This will mean the UI needs to be updated with the new payload.