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 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

Session Broker

• Implemented as a PSCustomObject 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):

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

Execution Context Integration

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

Trust Boundaries

• Workflow / Plan / Steps: untrusted, data-only, no secrets, no ScriptBlocks
• Session Broker: trusted, host-created, may contain ScriptMethods
• Providers: trusted code, consume 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 Session Broker may internally support different acquisition strategies, but Core is unaware of them.

Goals

• Introduce a 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 Session Broker contract exists in Core.
• Providers can acquire sessions via the execution context.
• Clear error is thrown if a provider requests a session and no broker is configured.
• Unit tests demonstrate:
  • Session Broker acquisition
  • Provider-side consumption via mocks
• Architecture documentation is updated to describe:
  • Session Broker concept
  • Trust boundaries
  • Interactive authentication rules

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 Session Broker without behavioral changes