architecture: provider authentication & session broker

[blindzero]

IdLE providers require authentication and connection context (e.g. credentials, tokens, sessions), but authentication mechanisms differ significantly between systems (on-prem AD vs. Entra ID / OAuth).

Currently, there is no unified, explicit abstraction for provider authentication and session handling. This leads to the risk of multiple authentication paths, inconsistent behavior, and later refactoring when introducing real cloud providers.

This issue introduces a Authentication Session Broker concept to centralize authentication and session acquisition in a host-controlled, provider-agnostic, and headless-compatible way.

Problem Statement

• Providers need authenticated access to external systems.
• Authentication mechanisms vary:
  • AD: PSCredential / integrated security
  • Entra ID: OAuth tokens, refresh, interactive flows
• Workflows, steps, and plans must remain data-only and must not contain secrets or ScriptBlocks.
• Providers should not implement their own authentication logic independently.

Proposed Solution

Authentication Session Broker

• Implemented as a PSCustomObject AuthSessionBroker with ScriptMethods (trusted code).
• Created and owned by the host / runner, not by workflows or steps.
• Exposed to the engine via the execution context.

Core Contract (conceptual):

• AcquireAuthSession(string Name, hashtable Options) → returns a auth session object
• Auth Session objects are opaque to Core and treated as trusted provider input.

Execution Context Integration

• The execution context exposes access to the configured Auth Session Broker.
• Providers request auth sessions by name (e.g. "AD", "EntraID").
• If no Auth Session Broker is configured, auth session acquisition fails with a clear, explicit error.

Trust Boundaries

• Workflow / Plan / Steps: untrusted, data-only, no secrets, no ScriptBlocks
• Auth Session Broker: trusted, host-created, may contain ScriptMethods
• Providers: trusted code, consume auth sessions but do not authenticate themselves

Interactive Authentication

• Interactive authentication (e.g. Entra ID browser login, device code flow) is allowed only in the host.
• Core and providers remain fully headless.
• The Auth Session Broker may internally support different acquisition strategies, but Core is unaware of them.

Decissions

• Providers key: AuthSessionBroker (no aliases)
• Naming: all “...Session” terms become “...AuthSession” in this feature
• ExecutionContext API: AcquireAuthSession(Name, Options)
• Options optional; $null → @{}
• Options must be data-only (no ScriptBlock values, including nested)
• Missing broker: throw InvalidOperationException with explicit remediation message
• Context injection: steps pass -Context $Context only when the provider method supports it (backwards compatible)

Goals

• Introduce a Auth Session Broker abstraction that providers can use to acquire authenticated sessions.
• Keep authentication logic outside of the Core engine (host responsibility).
• Ensure a single, consistent authentication path for all providers.
• Support both non-interactive and interactive authentication scenarios.
• Enable future providers (Entra ID, EXO, etc.) without refactoring existing ones.

Non-Goals

• No concrete Entra ID login implementation in Core.
• No UI, browser, or interactive logic in Core.
• No secret storage or secret management implementation.
• No provider-specific authentication logic in workflows or steps.

Acceptance Criteria

• A Auth Session Broker contract exists in Core.
• Providers can acquire auth sessions via the execution context.
• Clear error is thrown if a provider requests a auth session and no broker is configured.
• Unit tests demonstrate:
  • Auth Session Broker acquisition
  • Provider-side consumption via mocks
• Architecture documentation is updated to describe:
  • Auth Session Broker concept
  • Trust boundaries
  • Interactive authentication rules
• When broker missing, a deterministic exception is thrown with the documented message.
• Broker receives (Name, Options) with normalized/enriched options.
• Security: ScriptBlocks rejected in options.
• Existing providers/steps still work (no breaking changes).
• Pester + ScriptAnalyzer green.

Definition of Done

• Implementation merged with tests passing
• No breaking changes to workflow/step contracts
• Documentation updated (architecture / security)
• Design enables refactoring existing providers (e.g. AD) to use the Auth Session Broker without behavioral changes