feat: Add IdLE.Step.Mailbox.EnsurePermissions and ExchangeOnline provider support

docs/reference/providers/provider-exchangeonline.md

@@ -11,8 +11,8 @@ import ExoLeaverMailboxOffboarding from '@site/../examples/workflows/templates/e
 ## Summary
 
 - **Module:** `IdLE.Provider.ExchangeOnline`
-- **What it’s for:** Exchange Online mailbox configuration (type conversion, Out of Office, mailbox info)
-- **Targets:** Exchange Online via `ExchangeOnlineManagement` cmdlets
+- **What it’s for:** Exchange Online mailbox configuration (type conversion, Out of Office, delegate permissions, mailbox info)
+- **Targets:** Exchange Online via `ExchangeOnlineManagement` v3+ cmdlets (PowerShell 7+ compatible)
 - **Identity keys:** UPN (recommended), SMTP address, mailbox identifiers (provider-specific)
 
 ## When to use
@@ -23,6 +23,7 @@ Use this provider when your workflows need to manage **mailbox settings** in Exc
 - apply a safe baseline at onboarding (verify mailbox + ensure expected type)
 - convert mailbox type (e.g. user → shared for leavers)
 - set Out of Office messages (internal/external) and audience
+- converge delegate permissions (FullAccess, SendAs, SendOnBehalf)
 
 Non-goals:
 
@@ -33,9 +34,13 @@ Non-goals:
 
 ### Requirements
 
-- `ExchangeOnlineManagement` module available on the execution host
+- `ExchangeOnlineManagement` v3.0+ module available on the execution host (supports PowerShell 7+)
 - A host/runtime that establishes an Exchange Online session (delegated or app-only)
-- Permissions for the mailbox operations you intend to run (conversion, OOO, etc.)
+- Permissions for the mailbox operations you intend to run (conversion, OOO, permissions, etc.)
+
+> **PowerShell 7+ compatibility:** `ExchangeOnlineManagement` v3.0.0 and later support PowerShell 7+ on
+> Windows, macOS, and Linux via REST-based cmdlets. The “Windows only” limitation in earlier versions
+> applied to certificate-based app-only auth; the module itself runs cross-platform from v3.0 onwards.
 
 ### Install (PowerShell Gallery)
 
@@ -75,9 +80,33 @@ Mailbox steps typically reference that session via:
 
 Common step types using this provider include:
 
-- `IdLE.Step.Mailbox.GetInfo`
-- `IdLE.Step.Mailbox.EnsureType`
-- `IdLE.Step.Mailbox.EnsureOutOfOffice`
+| Step Type | Capability Required | Description |
+| --- | --- | --- |
+| `IdLE.Step.Mailbox.GetInfo` | `IdLE.Mailbox.Info.Read` | Read mailbox details |
+| `IdLE.Step.Mailbox.EnsureType` | `IdLE.Mailbox.Type.Ensure` | Convert mailbox type |
+| `IdLE.Step.Mailbox.EnsureOutOfOffice` | `IdLE.Mailbox.OutOfOffice.Ensure` | Configure Out of Office |
+| `IdLE.Step.Mailbox.EnsurePermissions` | `IdLE.Mailbox.Permissions.Ensure` | Converge delegate permissions |
+
+### Delegate permissions example
+
+```powershell
+@{
+    Name = 'Set Shared Mailbox Permissions'
+    Type = 'IdLE.Step.Mailbox.EnsurePermissions'
+    With = @{
+        Provider    = 'ExchangeOnline'
+        IdentityKey = 'shared@contoso.com'
+        Permissions = @(
+            @{ AssignedUser = 'user1@contoso.com'; Right = 'FullAccess';   Ensure = 'Present' }
+            @{ AssignedUser = 'user2@contoso.com'; Right = 'SendAs';       Ensure = 'Present' }
+            @{ AssignedUser = 'leaver@contoso.com'; Right = 'FullAccess';  Ensure = 'Absent'  }
+        )
+    }
+}
+```
+
+Supported rights: `FullAccess`, `SendAs`, `SendOnBehalf`.
+Each entry requires `AssignedUser` (UPN/SMTP), `Right`, and `Ensure` (`Present` or `Absent`).
 
 ## Configuration
 
@@ -97,6 +126,7 @@ To keep provider documentation focused and consistent, this page embeds only the
 - **Not connected**: ensure the host establishes an Exchange Online session before IdLE runs.
 - **Access denied**: the session identity must have permission to change mailbox settings.
 - **OOO formatting issues**: use `MessageFormat = 'Html'` and validate HTML in a test mailbox first.
+- **Permission changes not applied**: ensure the session identity has the *Mail Recipients* management role (or Exchange Administrator) required for `Add/Remove-MailboxPermission` and `Add/Remove-RecipientPermission`.
 
 ## Scenarios (link-only)
 

docs/reference/steps.md

@@ -13,6 +13,7 @@
 | [IdLE.Step.EnsureAttributes](steps/step-ensure-attributes.md) | ``IdLE.Steps.Common`` | Ensures that multiple identity attributes match their desired values. |
 | [IdLE.Step.EnsureEntitlement](steps/step-ensure-entitlement.md) | ``IdLE.Steps.Common`` | Ensures that an entitlement assignment is present or absent for an identity. |
 | [IdLE.Step.Mailbox.EnsureOutOfOffice](steps/step-mailbox-ensure-out-of-office.md) | ``IdLE.Steps.Mailbox`` | Ensures that a mailbox Out of Office (OOF) configuration matches the desired state. |
+| [IdLE.Step.Mailbox.EnsurePermissions](steps/step-mailbox-ensure-permissions.md) | ``IdLE.Steps.Mailbox`` | Ensures that mailbox delegate permissions match the desired state. |
 | [IdLE.Step.Mailbox.EnsureType](steps/step-mailbox-ensure-type.md) | ``IdLE.Steps.Mailbox`` | Ensures that a mailbox is of the desired type (User, Shared, Room, Equipment). |
 | [IdLE.Step.Mailbox.GetInfo](steps/step-mailbox-get-info.md) | ``IdLE.Steps.Mailbox`` | Retrieves mailbox details and returns a structured report. |
 | [IdLE.Step.MoveIdentity](steps/step-move-identity.md) | ``IdLE.Steps.Common`` | Moves an identity to a different container/OU in the target system. |

docs/reference/steps/step-mailbox-ensure-permissions.md

@@ -0,0 +1,80 @@
+# IdLE.Step.Mailbox.EnsurePermissions
+
+> Generated file. Do not edit by hand.
+> Source: tools/Generate-IdleStepReference.ps1
+
+## Summary
+
+- **Step Type**: `IdLE.Step.Mailbox.EnsurePermissions`
+- **Module**: `IdLE.Steps.Mailbox`
+- **Implementation**: `Invoke-IdleStepMailboxPermissionsEnsure`
+- **Idempotent**: `Yes`
+
+## Synopsis
+
+Ensures that mailbox delegate permissions match the desired state.
+
+## Description
+
+The host must supply a provider instance via
+Context.Providers[<ProviderAlias>]. The provider must implement an EnsureMailboxPermissions
+method with the signature (IdentityKey, Permissions, AuthSession) and return an object
+that contains a boolean property 'Changed'.
+
+The step is idempotent by design: it converges mailbox delegate permissions to the desired
+state by computing the delta between current and desired permissions and applying only the
+necessary changes.
+
+Supported rights (v1):
+
+- FullAccess
+
+- SendAs
+
+- SendOnBehalf
+
+Permissions array shape (data-only):
+Each entry must be a hashtable with:
+
+- AssignedUser: string (required) - UPN or SMTP address of the delegate
+
+- Right: 'FullAccess' | 'SendAs' | 'SendOnBehalf' (required)
+
+- Ensure: 'Present' | 'Absent' (required)
+
+Authentication:
+
+- If With.AuthSessionName is present, the step acquires an auth session via
+  Context.AcquireAuthSession(Name, Options) and passes it to the provider method.
+
+- If With.AuthSessionName is absent, defaults to With.Provider value (e.g., 'ExchangeOnline').
+
+- With.AuthSessionOptions (optional, hashtable) is passed to the broker for
+  session selection (e.g., @\{ Role = 'Admin' \}).
+
+## Inputs (With.*)
+
+The following keys are required in the step's ``With`` configuration:
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `IdentityKey` | Yes | Unique identifier for the identity |
+| `Permissions` | Yes | See step description for details |
+
+## Example
+
+```powershell
+@{
+  Name = 'IdLE.Step.Mailbox.EnsurePermissions Example'
+  Type = 'IdLE.Step.Mailbox.EnsurePermissions'
+  With = @{
+    IdentityKey          = 'user.name'
+    Permissions          = '<value>'
+  }
+}
+```
+
+## See Also
+
+- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Providers](../providers.md) - Available provider implementations

src/IdLE.Core/Private/Get-IdleStepRegistry.ps1

@@ -199,5 +199,12 @@ function Get-IdleStepRegistry {
         }
     }
 
+    if (-not $registry.ContainsKey('IdLE.Step.Mailbox.EnsurePermissions')) {
+        $handler = Resolve-IdleStepHandlerName -CommandName 'Invoke-IdleStepMailboxPermissionsEnsure' -ModuleName 'IdLE.Steps.Mailbox'
+        if (-not [string]::IsNullOrWhiteSpace($handler)) {
+            $registry['IdLE.Step.Mailbox.EnsurePermissions'] = $handler
+        }
+    }
+
     return $registry
 }