Idle.Provider.Intune 3 - Device.Retire capability

[blindzero]

Problem Statement

For BYOD compliance policies, IdLE should be able to initiate Intune’s BYOD “Retire / Wipe company data” action in a controlled, safe, testable way.

Because this is a destructive action, IdLE must:

• never guess the target device
• fail fast if the device is not uniquely identified
• support human-in-the-loop flows (operator identifies device, then provides confirmation / device id)

Proposed Solution

1) Add Intune provider action capability (v1)

Extend IdLE.Provider.Intune with a new capability:

• IdLE.Device.Retire

Safety rules:

• MUST require an explicit device id as input.
• MUST fail fast if device id is missing.
• MUST NOT implement “best-effort matching” or silent heuristics.
• Must emit a structured event/log entry describing the action target (safe fields only).

2) Integration expectations (BYOD policy)

This capability is intended to be used with:

• populated device context under Request.Context.Devices.Intune.ManagedDevices[] (for operator identification)
• runtime preconditions (Blocked) to prevent disablement until retire is confirmed

The exact workflow orchestration (manual vs automated) is host/workflow-defined.

3) Step wrapper (optional follow-up)

Provider-agnostic step wrappers (e.g., IdLE.Step.Device.Retire) can be introduced in a follow-up issue, once the capability contract is proven stable.

Alternatives Considered

1. Implement retire/wipe only via host scripts

• Reduces portability and consistent testing.

2. Allow selection strategies / fuzzy matching

• Unsafe; may target the wrong device. Not acceptable for destructive actions.

Impact

• Introduces a destructive action capability, requiring careful review, tests, and documentation.
• Enables automated or semi-automated BYOD flows when device id is known.

Dependencies

• Requires Intune Issue 1 (provider module exists; device schema established).
• Recommended: runtime preconditions (Blocked) to enforce policy ordering.
• Recommended: request schema Request.Intent / Request.Context.

Definition of Done (Step-0-Ready / Agent-Safe)

Design / Contracts

• Define IdLE.Device.Retire contract:
  • required inputs (device id)
  • expected outputs and events
  • error behavior (missing id, not found, permission errors)
• Define safety constraints explicitly (no heuristic selection).

Implementation

• Implement IdLE.Device.Retire in IdLE.Provider.Intune.
• Ensure action uses explicit device id and fails fast otherwise.
• Emit a safe structured event describing what was targeted.

Tests (Pester)

• Unit test: missing device id -> fails fast.
• Contract test: action is invoked with correct device id.
• Contract test: not found / permission errors are surfaced consistently.

Docs / Examples

• Update Intune provider docs with:
  • required permissions/scopes for retire
  • explicit warnings about destructive behavior
  • example usage with explicit device id
• Example workflow snippet showing:
  • context device list for identification
  • retire call with explicit device id (optional)
  • runtime precondition blocks disable until confirmed

Non-Goals (explicit)

• No automatic device selection heuristics.
• No interactive UI in IdLE.
• No provider-agnostic step wrapper in this issue (follow-up if needed).