feat(core): add AuthSessionBroker acquisition via ExecutionContext

.gitattributes

@@ -4,4 +4,5 @@
 *.yaml text eol=lf
 *.ps1  text eol=lf
 *.psm1 text eol=lf
-*.psd1 text eol=lf
+*.psd1 text eol=lf
+*.html text eol=lf

PSScriptAnalyzerSettings.psd1

@@ -36,13 +36,13 @@
 
     Rules        = @{
         PSUseConsistentIndentation = @{
-            Enable             = $true
-            IndentationSize    = 4
+            Enable              = $true
+            IndentationSize     = 4
             PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
-            Kind               = 'space'
+            Kind                = 'space'
         }
 
-        PSUseConsistentWhitespace  = @{
+        PSUseConsistentWhitespace = @{
             Enable                          = $true
             CheckInnerBrace                 = $true
             CheckOpenBrace                  = $true
@@ -52,7 +52,7 @@
             CheckPipeForRedundantWhitespace = $false
             CheckSeparator                  = $true
             CheckParameter                  = $false
-            IgnoreAssignmentOperatorInsideHashTable = $false
+            IgnoreAssignmentOperatorInsideHashTable = $true
         }
     }
 }

STYLEGUIDE.md

@@ -28,6 +28,7 @@ It follows widely accepted **GitHub and PowerShell community conventions**.
 - Verb-Noun cmdlet naming
 - Singular nouns
 - Avoid abbreviations
+- Only approved Verbs
 
 ---
 
@@ -87,7 +88,7 @@ Steps must:
 Providers:
 
 - handle authentication
-- use `ExecutionContext.AcquireSession()`
+- use `ExecutionContext.AcquireAuthSession()`
 - must be mockable
 - must not assume global state
 
@@ -129,6 +130,7 @@ This style guide focuses on **in-code documentation rules** (comment-based help,
 - validate early
 - write tests
 - document decisions
+- keep surface small, no private function exports
 
 ### Don't
 

docs/advanced/extensibility.md

@@ -26,9 +26,35 @@ A new provider typically involves:
 
 1. A contract interface (if not already present)
 2. A provider implementation module
-3. Session acquisition via host execution context
+3. Auth session acquisition via host execution context (AuthSessionBroker)
 4. Contract tests and unit tests
 
+### Auth session acquisition (AuthSessionBroker)
+
+IdLE keeps authentication out of the core engine. Hosts provide an auth session broker
+that is responsible for obtaining and caching authenticated runtime handles (tokens,
+Graph clients, Exchange Online sessions, LDAP binds, etc.).
+
+- Hosts MUST pass the broker via `Providers.AuthSessionBroker`.
+- Providers SHOULD acquire sessions through the execution context:
+  - `Context.AcquireAuthSession(Name, Options)`
+
+Broker contract:
+
+- The broker MUST expose an `AcquireAuthSession(Name, Options)` method.
+- `Name` is a routing key (for example: `MicrosoftGraph`, `ExchangeOnline`, `ActiveDirectory`).
+- `Options` is optional (`$null` is treated as an empty hashtable) and must be data-only:
+  - ScriptBlock values are rejected, including nested values.
+- The engine enriches options with `CorrelationId` and `Actor` when available.
+- The engine deep-copies `Options` before invoking the broker; brokers MUST treat
+  options as immutable and MUST NOT mutate nested values.
+
+Security notes:
+
+- Do not embed credentials directly in `Options`.
+- Treat `Options` as configuration input, not a secret store.
+- Use host secret management and keep secrets out of plans, events, and exports.
+
 ### Capability Advertisement
 
 Providers must explicitly advertise their supported capabilities via a
@@ -56,6 +82,7 @@ Do not add:
 
 - interactive prompts
 - authentication code inside steps
+- authentication flows inside providers (use AuthSessionBroker)
 - UI or web server dependencies
 
 Those belong in a host application.
@@ -68,3 +95,7 @@ Steps are executed via a host-provided step registry.
 - The host maps this identifier to a **function name** (string) in the step registry.
 
 ScriptBlock handlers are intentionally not supported as a secure default.
+
+Step handlers may optionally declare a `Context` parameter.
+For backwards compatibility, the engine passes `-Context` only when the handler
+supports it.

docs/reference/events-and-observability.md

@@ -92,6 +92,24 @@ Buffering is the default because it keeps the core:
 
 ---
 
+### Optional streaming to a host sink
+
+Hosts may provide an **event sink** to receive events as they happen.
+
+The engine expects an object with a `WriteEvent(event)` method.
+If present, the engine forwards each event to that sink **in addition to** buffering
+events in the execution result.
+
+This enables patterns such as:
+
+- forward events to a central logging system
+- push events to a message bus
+- render progress updates in an interactive host
+
+The engine still does not assume anything about formatting, persistence, or transport.
+
+---
+
 ## Usage
 
 ### Typical consumption patterns
@@ -142,6 +160,24 @@ This separation ensures that IdLE remains portable and reusable across environme
 
 ---
 
+## Security and sensitive data
+
+Events are a primary observability surface and therefore a common place where sensitive
+values can accidentally leak.
+
+Guidelines:
+
+- **Do not emit secrets** in `Event.Data` (tokens, passwords, client secrets, API keys, certificates).
+- Prefer **references** (for example: identity IDs, step names, correlation IDs) over raw payloads.
+- The engine applies **redaction** at output boundaries (buffered events and host sinks) for
+  common sensitive key names (for example: `password`, `token`, `secret`, `apiKey`).
+  Redaction is a safety net, not a design strategy.
+- When acquiring authentication sessions, use `Providers.AuthSessionBroker` via
+  `Context.AcquireAuthSession(Name, Options)`. Auth session options are a data-only boundary
+  and reject ScriptBlocks.
+
+---
+
 ## Common pitfalls
 
 ### “Why don’t I see any events?”

docs/reference/providers-and-contracts.md

@@ -160,6 +160,72 @@ their implementation beyond contract usage.
 
 ---
 
+## Auth session acquisition (AuthSessionBroker)
+
+Many providers require authenticated connections (tokens, API clients, remote sessions).
+IdLE keeps authentication out of the engine and out of individual providers by using a
+host-supplied broker.
+
+### Contract
+
+The host injects an **AuthSessionBroker** into the providers map:
+
+- `Providers.AuthSessionBroker`
+
+During execution, steps and providers may acquire sessions via the execution context:
+
+- `Context.AcquireAuthSession(Name, Options)`
+
+Where:
+
+- `Name` identifies the requested session (e.g. `Graph`, `ExchangeOnline`, `Ldap`, ...).
+- `Options` is an optional **data-only** hashtable.
+  - `$null` is treated as an empty hashtable.
+  - ScriptBlocks are rejected, including nested values.
+
+The broker must expose a method:
+
+- `AcquireAuthSession(Name, Options)`
+
+### Responsibility boundaries
+
+- **Engine**
+  - Provides `Context.AcquireAuthSession()` as a stable API.
+  - Enforces the data-only boundary for `Options`.
+  - Does not implement authentication.
+
+- **Host**
+  - Implements and configures the AuthSessionBroker.
+  - Decides how to authenticate (interactive, managed identity, certificate, secrets, ...).
+  - Must ensure secrets are not leaked into plans, events, or exports.
+
+- **Providers / Steps**
+  - Request sessions through the execution context.
+  - Must not perform their own authentication flows.
+
+### Enrichment
+
+The execution context may enrich the broker request with common run metadata, such as:
+
+- `CorrelationId`
+- `Actor`
+
+Providers and steps should treat these values as optional.
+
+---
+
+## Execution context injection (backwards compatibility)
+
+IdLE step handlers can optionally accept a `Context` parameter.
+
+To remain backwards compatible, the engine passes `-Context $Context` **only if** the
+handler supports a `Context` parameter.
+
+Guidance:
+
+- New step handlers should accept `Context` to access providers, event sink, and auth session acquisition.
+- Existing handlers without `Context` continue to work unchanged.
+
 ## Common pitfalls
 
 ### Treating providers as part of the engine

src/IdLE.Core/IdLE.Core.psm1

@@ -2,7 +2,7 @@
 
 Set-StrictMode -Version Latest
 
-$PublicPath  = Join-Path -Path $PSScriptRoot -ChildPath 'Public'
+$PublicPath = Join-Path -Path $PSScriptRoot -ChildPath 'Public'
 $PrivatePath = Join-Path -Path $PSScriptRoot -ChildPath 'Private'
 
 foreach ($path in @($PrivatePath, $PublicPath)) {

src/IdLE.Core/Private/Assert-IdleNoScriptBlockInAuthSessionOptions.ps1

@@ -0,0 +1,49 @@
+# Validates that auth session options do not contain ScriptBlock objects.
+# Recursively walks hashtables, enumerables, and PSCustomObjects.
+# Enforces the security boundary: auth session options must be data-only.
+
+function Assert-IdleNoScriptBlockInAuthSessionOptions {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [object] $InputObject,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string] $Path
+    )
+
+    if ($null -eq $InputObject) { return }
+
+    if ($InputObject -is [scriptblock]) {
+        throw [System.ArgumentException]::new(
+            "ScriptBlocks are not allowed in auth session options. Found at: $Path",
+            $Path
+        )
+    }
+
+    if ($InputObject -is [System.Collections.IDictionary]) {
+        foreach ($key in $InputObject.Keys) {
+            Assert-IdleNoScriptBlockInAuthSessionOptions -InputObject $InputObject[$key] -Path "$Path.$key"
+        }
+        return
+    }
+
+    if (($InputObject -is [System.Collections.IEnumerable]) -and ($InputObject -isnot [string])) {
+        $i = 0
+        foreach ($item in $InputObject) {
+            Assert-IdleNoScriptBlockInAuthSessionOptions -InputObject $item -Path "$Path[$i]"
+            $i++
+        }
+        return
+    }
+
+    if ($InputObject -is [pscustomobject]) {
+        foreach ($p in $InputObject.PSObject.Properties) {
+            if ($p.MemberType -eq 'NoteProperty') {
+                Assert-IdleNoScriptBlockInAuthSessionOptions -InputObject $p.Value -Path "$Path.$($p.Name)"
+            }
+        }
+    }
+}

src/IdLE.Core/Private/ConvertTo-IdlePlanExportObject.ps1

@@ -102,13 +102,13 @@ function ConvertTo-IdlePlanExportObject {
             # When present, export these as the canonical request.input payload.
             $identityKeys = Get-FirstPropertyValue -Object $request -Names @('IdentityKeys', 'IdentityKey', 'Keys')
             $desiredState = Get-FirstPropertyValue -Object $request -Names @('DesiredState', 'TargetState')
-            $changes      = Get-FirstPropertyValue -Object $request -Names @('Changes', 'Delta')
+            $changes = Get-FirstPropertyValue -Object $request -Names @('Changes', 'Delta')
 
             if ($null -ne $identityKeys -or $null -ne $desiredState -or $null -ne $changes) {
                 $requestInput = New-OrderedMap
                 $requestInput.identityKeys = $identityKeys
                 $requestInput.desiredState = $desiredState
-                $requestInput.changes      = $changes
+                $requestInput.changes = $changes
             }
         }
     }
@@ -138,10 +138,10 @@ function ConvertTo-IdlePlanExportObject {
     }
 
     $requestMap = New-OrderedMap
-    $requestMap.type          = $requestType
+    $requestMap.type = $requestType
     $requestMap.correlationId = $correlationId
-    $requestMap.actor         = $actor
-    $requestMap.input         = $redactedRequestInput
+    $requestMap.actor = $actor
+    $requestMap.input = $redactedRequestInput
 
     # ---- Plan block ----------------------------------------------------------
     $planId = ConvertTo-NullIfEmptyString -Value (

src/IdLE.Core/Private/Copy-IdleDataObject.ps1

@@ -0,0 +1,67 @@
+function Copy-IdleDataObject {
+    <#
+    .SYNOPSIS
+    Creates a deep-ish, data-only copy of an object.
+
+    .DESCRIPTION
+    This helper is used to snapshot data-like objects so that exported or executed
+    artifacts do not retain references to caller-owned objects.
+
+    NOTE:
+    This is intentionally conservative and only supports data-like objects:
+    - Hashtable / OrderedDictionary
+    - PSCustomObject / NoteProperties
+    - Arrays/lists
+    - Primitive types
+
+    ScriptBlocks and other executable objects are rejected by upstream validation.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [AllowNull()]
+        [object] $Value
+    )
+
+    if ($null -eq $Value) { return $null }
+
+    # Primitive / immutable types should be returned as-is before property inspection.
+    # This prevents strings from being converted to PSCustomObject with Length property.
+    if ($Value -is [string] -or
+        $Value -is [int] -or
+        $Value -is [long] -or
+        $Value -is [double] -or
+        $Value -is [decimal] -or
+        $Value -is [bool] -or
+        $Value -is [datetime] -or
+        $Value -is [guid]) {
+        return $Value
+    }
+
+    if ($Value -is [System.Collections.IDictionary]) {
+        $copy = @{}
+        foreach ($k in $Value.Keys) {
+            $copy[$k] = Copy-IdleDataObject -Value $Value[$k]
+        }
+        return $copy
+    }
+
+    if ($Value -is [System.Collections.IEnumerable] -and $Value -isnot [string]) {
+        $arr = @()
+        foreach ($item in $Value) {
+            $arr += Copy-IdleDataObject -Value $item
+        }
+        return $arr
+    }
+
+    $props = @($Value.PSObject.Properties | Where-Object MemberType -in @('NoteProperty', 'Property'))
+    if ($null -ne $props -and @($props).Count -gt 0) {
+        $o = [ordered]@{}
+        foreach ($p in $props) {
+            $o[$p.Name] = Copy-IdleDataObject -Value $p.Value
+        }
+        return [pscustomobject]$o
+    }
+
+    return $Value
+}