refactor Provider.AD: Route authentication via AuthSessionBroker

[blindzero]

Context

IdLE keeps authentication out of the core engine and out of workflow/step configuration.
Hosts provide an AuthSessionBroker via Providers.AuthSessionBroker, and steps/providers can acquire sessions via
Context.AcquireAuthSession(Name, Options).

The Active Directory provider introduced in #46 still supports direct credential injection and includes examples
that can encourage interactive auth (e.g., Get-Credential). This deviates from the documented project guidance:
providers/steps must not run authentication flows themselves; authentication must be host-driven via the broker.

This issue aligns IdLE.Provider.AD (and the relevant built-in step contract usage) with the AuthSessionBroker model
so that real-world scenarios like multiple admin accounts per system (Tier0 vs. Admin) can be implemented without
secrets in plans/workflows.

Problem

Example real-world requirement:

• Step 1 must use a dedicated Tier0 AD admin account.
• Step 2 must use a separate admin account.
• Both accounts are different from the OS user running the host process.

Today, the AD provider can be configured with credentials at construction time, but the engine/steps do not provide a
standard, data-only way to select different auth contexts per step while keeping authentication centralized in the host.

Goals

• Route AD authentication/session selection via Context.AcquireAuthSession(...) (AuthSessionBroker).
• Support multiple auth contexts (e.g., Tier0 vs. Admin) selectable per step using data-only metadata.
• Keep workflow definitions and step parameters data-only (no ScriptBlocks, no secrets).
• Remove interactive authentication from provider examples.
• Add/adjust tests to keep this behavior deterministic and mockable.

Non-goals

• No interactive authentication inside IdLE.Core, steps, or providers.
• No requirement to implement MFA/DeviceCode for AD itself.
  (The mechanism must be compatible with MFA/DeviceCode for other systems, but AD usage will typically remain
  PSCredential/integrated auth behind the broker.)
• No live AD integration tests as part of unit/contract tests.

Proposed Design (recommended)

A) Step-level, data-only auth routing keys

Introduce optional With.* keys for steps that call providers:

• With.AuthSessionName (string)
  • Example: ActiveDirectory
• With.AuthSessionOptions (hashtable, data-only)
  • Example: @{ Role = 'Tier0' } or @{ Role = 'Admin' }

Notes:

• With.AuthSessionOptions must remain data-only and must be validated the same way as other untrusted inputs
  (ScriptBlocks rejected, including nested values).
• Options must not contain secrets. Secrets are managed by the host and are not allowed in plans/events/exports.

B) Acquire auth session at execution time

In step execution (for steps that call providers):

1. If With.AuthSessionName is present, acquire a session:
   • $authSession = $Context.AcquireAuthSession($With.AuthSessionName, $With.AuthSessionOptions)
2. If not present, $authSession = $null.

C) Pass AuthSession to provider calls when supported (backwards compatible)

Update the provider contract usage in the relevant step(s) so that provider methods can accept an optional session.
Pattern:

• If the provider method supports an AuthSession (or Session) parameter, pass it.
• Otherwise, call the legacy signature.

This avoids breaking existing providers while enabling broker-driven authentication.

D) Update AD provider to consume AuthSession

• Update AD provider methods to accept an optional AuthSession argument.
• The AD provider should interpret the session object in a documented way. Default expectation:
  • session contains a PSCredential (directly, or as a property like .Credential).
• The AD provider must not prompt or run its own login flow.

E) Deprecation path for -Credential on AD provider

• Keep -Credential temporarily for backwards compatibility, but mark as deprecated (warning).
• Remove interactive examples (e.g., Get-Credential) and replace with broker-based examples.
• The recommended usage becomes: host implements broker and returns sessions based on Name + Options.

Alternatives considered

Alternative 1: Two AD provider instances selected via With.Provider

• Create AD_Tier0 and AD_Admin provider instances (each with embedded credentials) and select via With.Provider.
• Works today, but keeps credential handling in provider construction and does not standardize auth routing.

Alternative 2: Provider calls broker directly

• Provider would call Context.AcquireAuthSession(...) itself.
• Requires passing Context into provider calls or binding context into provider objects, which complicates the contract.

Recommendation remains: acquire session in steps (using Context) and pass session to providers when supported.

Acceptance Criteria (Definition of Done)

• AD provider supports an optional AuthSession input (documented expected shape).
• Built-in step(s) that call the AD provider support optional With.AuthSessionName and With.AuthSessionOptions.
• When auth routing keys are present, the step acquires the session via Context.AcquireAuthSession(...).
• The step passes the acquired session to the provider method if the provider supports it; otherwise it falls back to
  the legacy signature.
• ScriptBlocks in With.AuthSessionOptions are rejected (including nested values).
• AD provider examples do not use Get-Credential and do not show direct credential injection as the primary path.
• Tests:
  • Unit test: step acquires session via mocked broker and passes it to provider.
  • Unit test: provider lacking AuthSession parameter still works (fallback call).
  • Unit test: ScriptBlocks in auth options are rejected.
• Documentation updated where required (provider contract guidance and step metadata guidance).

Work breakdown

1. Update the relevant step(s) (likely EnsureAttribute) to support With.AuthSessionName and With.AuthSessionOptions.
2. Implement optional session passing to provider methods (parameter detection / fallback signature).
3. Update AD provider to accept and use AuthSession.
4. Update examples to demonstrate Tier0/Admin scenario using broker options (no interactive prompts).
5. Add tests (Pester) for routing, fallback, and ScriptBlock rejection.
6. Update docs as needed (contracts + step metadata).

References

• IdLE.Provider.AD (On-Prem AD) MVP (Windows-only) #46 (ActiveDirectory provider introduced)
• architecture: provider authentication & session broker #77 (AuthSessionBroker architecture and execution context acquisition)