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

[Copilot]

No capability existed to converge mailbox delegate permissions (FullAccess, SendAs, SendOnBehalf) within an IdLE workflow, forcing hosts to implement this outside the plan/execute boundary.

New step: IdLE.Step.Mailbox.EnsurePermissions

Provider-agnostic, idempotent step that converges delegate permissions for a mailbox. Supports all three v1 rights; validates data-only input and rejects ScriptBlocks.

@{
    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 = 'user3@contoso.com'; Right = 'SendOnBehalf'; Ensure = 'Absent'  }
        )
    }
}

Capability

• Added IdLE.Mailbox.Permissions.Ensure to the step metadata catalog and to GetCapabilities on the ExchangeOnline provider.

ExchangeOnline provider

• New EnsureMailboxPermissions ScriptMethod — reads current state per right type, computes delta, applies only necessary changes.
• Eight new adapter methods behind the testable boundary:
  • FullAccess: GetMailboxPermissions, AddMailboxPermission, RemoveMailboxPermission → wraps Get/Add/Remove-MailboxPermission
  • SendAs: GetRecipientPermissions, AddRecipientPermission, RemoveRecipientPermission → wraps Get/Add/Remove-RecipientPermission
  • SendOnBehalf: GetMailboxSendOnBehalf, SetMailboxSendOnBehalf → wraps Get-Mailbox / Set-Mailbox -GrantSendOnBehalfTo

PowerShell 7+ compatibility: ExchangeOnlineManagement v3.0.0+ supports PowerShell 7+ cross-platform via REST-based cmdlets. The adapter wraps these cmdlets following the same pattern as the existing mailbox adapter methods. The "Windows only" note in earlier provider docs referred only to certificate-based app-only auth.

Module surface

• Invoke-IdleStepMailboxPermissionsEnsure added to FunctionsToExport in both the .psd1 manifest and .psm1.
• IdLE.Step.Mailbox.EnsurePermissions registered in src/IdLE.Core/Private/Get-IdleStepRegistry.ps1 so the engine can dispatch the step in workflows.

Documentation

• docs/reference/steps.md regenerated (via Generate-IdleStepReference.ps1) to include the new step type.
• docs/reference/steps/step-mailbox-ensure-permissions.md generated with full step reference.
• docs/reference/providers/provider-exchangeonline.md updated with the new capability in the step types table, a delegate permissions workflow example snippet, a PowerShell 7+ / ExchangeOnlineManagement v3+ compatibility note, and a permissions-related troubleshooting entry.
• src/IdLE.Steps.Mailbox/README.md updated to list the new step type.
• website/sidebars.js updated to include step-mailbox-ensure-permissions in the Step Reference sidebar navigation, alongside the other mailbox step pages.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ExchangeOnline - mailbox permissions</issue_title>
<issue_description>## Problem Statement

There is currently no capability or Step Type in IdLE to set mailbox delegate permissions (e.g. FullAccess, SendAs, SendOnBehalf) for Exchange Online mailboxes.

For real-world JML workflows this is a common requirement (shared mailboxes, assistants, team mailboxes, role mailboxes). Today, workflow authors must implement this outside IdLE, which breaks:

• portability (logic moves into host scripts)
• deterministic plan/execute (permissions changes are not represented in the plan)
• testability (no contract-based/mocked implementation)

Proposed Solution

Add a provider-agnostic step and capability for mailbox permission convergence.

New Step Type

• IdLE.Step.Mailbox.EnsurePermissions
  • Purpose: idempotently converge delegate permissions for a mailbox.
  • Module: IdLE.Steps.Mailbox

Capability

• IdLE.Mailbox.Permissions.Ensure
  • Used for planning-time validation.

Step input contract (With)

With = @{
    Provider        = 'ExchangeOnline'        # optional, defaults to 'ExchangeOnline'
    IdentityKey     = 'shared@contoso.com'    # mailbox identity (UPN/SMTP)

    # Target permissions (data-only)
    Permissions     = @(
        @{ AssignedUser = 'user1@contoso.com'; Right = 'FullAccess'; Ensure = 'Present' }
        @{ AssignedUser = 'user2@contoso.com'; Right = 'SendAs';     Ensure = 'Present' }
        @{ AssignedUser = 'user3@contoso.com'; Right = 'SendOnBehalf'; Ensure = 'Absent' }
    )

    # AuthSession selection (same convention as other mailbox steps)
    AuthSessionName    = 'ExchangeOnline'     # optional, defaults to Provider
    AuthSessionOptions = @{ Role = 'Admin' }  # optional
}

Supported rights (v1)

Minimum viable scope (v1):

• FullAccess
• SendAs
• SendOnBehalf

Non-goals for v1 (nice-to-have later):

• folder-level permissions
• calendar delegation/processing options
• auto-mapping behavior controls

Provider contract extension

Extend the mailbox provider contract with a single, mockable method (name is a suggestion):

• EnsureMailboxPermissions(MailboxIdentity, Permissions, AuthSession)

Where Permissions is a data-only array (see above) and the provider returns a data-only result describing:

• desired vs. current
• computed changes (add/remove)
• performed operations (for execution)

Exchange Online provider implementation

In IdLE.Provider.ExchangeOnline, implement the contract using an internal adapter layer so it is testable without calling EXO:

• full access: Get-MailboxPermission, Add-MailboxPermission, Remove-MailboxPermission
• send as: Get-RecipientPermission, Add-RecipientPermission, Remove-RecipientPermission
• send on behalf: Get-Mailbox (or existing GetMailbox) + Set-Mailbox -GrantSendOnBehalfTo

Step behavior

• Read current state via provider.
• Compute delta deterministically.
• If no changes required: return Changed = $false.
• If changes required: execute provider method(s) and return Changed = $true.
• Emit structured events (no secrets).

Tests

• Unit tests for the step (delta computation, validation, idempotency) using a mock provider.
• Provider contract tests for Exchange Online provider using a mocked adapter.

Documentation

• Add step documentation via the generated step reference (docs/reference/steps.md) by updating step help and running the generator.
• Add/extend Exchange Online provider docs to include:
  • required capability
  • example workflow snippet for mailbox permissions

Impact

• New capability + new Step Type only. No breaking changes expected.
• Exchange Online provider gains an additional method and capability advertisement.
• Workflows can start using the new step immediately once provider supports it.

Additional Context

Repository review indicates IdLE.Steps.Mailbox currently exports only:

• IdLE.Step.Mailbox.GetInfo
• IdLE.Step.Mailbox.EnsureType
• IdLE.Step.Mailbox.EnsureOutOfOffice

and the Exchange Online provider advertises mailbox capabilities for info/type/OOO only.
This enhancement covers the missing mailbox delegate permissions use case.

Consider using pure Graph Access with Scope, not ExchangeOnlineManagement module, depending what is more likely already available or easier to integrate.
</issue_description>

<agent_instructions>- No interactive prompts.

• No secrets in logs/events; rely on AuthSessionBroker.
• Provider calls must be behind a mockable adapter layer.
• All inputs are data-only; reject ScriptBlocks.
  </agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes ExchangeOnline - mailbox permissions #226

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[blindzero]

@copilot did you make sure not to use ExchangeOnlineManagement as it seems to have issues with PowerShell Core which is our minimum? EXOM seems to be only available for PowerShell Desk?
How are other EXO Adapter Integration handling it?

Make sure also to include this in the documentations which are not generated automatically.

[github-actions]

Code Coverage Report

Overall Project	73.18%	🍏

There is no coverage information present for the Files changed

[Copilot]

@copilot did you make sure not to use ExchangeOnlineManagement as it seems to have issues with PowerShell Core which is our minimum? EXOM seems to be only available for PowerShell Desk?
How are other ...

The new permission adapter methods (Get/Add/Remove-MailboxPermission, Get/Add/Remove-RecipientPermission, Get/Set-Mailbox for SendOnBehalf) follow the same pattern as the existing adapter — which was already using ExchangeOnlineManagement before this PR. ExchangeOnlineManagement v3.0+ fully supports PowerShell 7+ on Windows, macOS, and Linux via REST-based cmdlets; the "Windows only" caveat in earlier docs referred only to certificate-based app-only auth, not the module itself.

Documentation has been updated in commit 5841738:

• docs/reference/providers/provider-exchangeonline.md — clarified PowerShell 7+ / EXO v3+ compatibility, added the new step type to the capability table, and added a delegate permissions workflow snippet
• docs/reference/steps.md and docs/reference/steps/step-mailbox-ensure-permissions.md — regenerated via Generate-IdleStepReference.ps1
• src/IdLE.Steps.Mailbox/README.md — added the new step to the list
• src/IdLE.Core/Private/Get-IdleStepRegistry.ps1 — registered the new step type so the engine can dispatch it

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7dc3881441

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This pull request adds a new IdLE step type IdLE.Step.Mailbox.EnsurePermissions for idempotent mailbox delegate permissions management in Exchange Online. The implementation follows established IdLE patterns for provider-agnostic steps with adapter-based testability.

Changes:

• New step type for convergent mailbox permissions (FullAccess, SendAs, SendOnBehalf) with data-only validation and ScriptBlock rejection
• Exchange Online provider extended with EnsureMailboxPermissions method and 8 new adapter methods behind the testable boundary
• New capability IdLE.Mailbox.Permissions.Ensure added to step metadata catalog and provider advertisements

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/IdLE.Steps.Mailbox/Public/Invoke-IdleStepMailboxPermissionsEnsure.ps1	New step implementation with validation, security boundaries, and comprehensive comment-based help
src/IdLE.Steps.Mailbox/Public/Get-IdleStepMetadataCatalog.ps1	Added EnsurePermissions step metadata with required capabilities
src/IdLE.Steps.Mailbox/IdLE.Steps.Mailbox.psm1	Exported new step function
src/IdLE.Steps.Mailbox/IdLE.Steps.Mailbox.psd1	Added step function to manifest FunctionsToExport
src/IdLE.Provider.ExchangeOnline/Public/New-IdleExchangeOnlineProvider.ps1	Added EnsureMailboxPermissions ScriptMethod and new capability advertisement
src/IdLE.Provider.ExchangeOnline/Private/New-IdleExchangeOnlineAdapter.ps1	Added 8 permission adapter methods (Get/Add/Remove for FullAccess, SendAs, SendOnBehalf)
tests/Steps/Invoke-IdleStepMailboxPermissionsEnsure.Tests.ps1	Comprehensive step tests covering behavior, validation, idempotency, and security boundaries
tests/Providers/ExchangeOnlineProvider.Tests.ps1	Provider contract tests with fake adapter for all three permission types