Implement Stage A: rule engine, validation, audit, and safety gates

Completes 109 of 121 tasks. Every remaining task needs a tenant connection (T055, T056, T101-T103) or an Azure Automation account (T115-T121). 354 offline Pester tests PASS Engine purity (Principle IV) PASS Sanitization (SC-013) PASS (156 files) Graph module loaded in tests none (SC-008 holds) What landed - Four-layer configuration validation with stable finding codes, covering every VR-002 and VR-003 condition, plus a 23-fixture invalid-config corpus - Run loop, audit records (NDJSON through a single sink), summaries, reconciliation, and exit codes 0-6 - Persistence behind a single write-body builder whose result always has exactly one key - Invoke-PersonaEngine.ps1 and Edit-PersonaEngineConfig.ps1 - Six docs, two pipelines, traceability matrix, V-5a and sanitization records Three deviations from tasks.md, each recorded in its status block T033 is not in Resolve-UserPersona. evaluationErrorThreshold is run-level state and the rule engine is pure; a counter there would break Principle IV. It lives in New-PersonaRunCounter and is applied in the run loop. A new src/Engine/ layer holds Invoke-PersonaEngineRun. The entry script imports the manifest, which requires Microsoft.Graph.Authentication, so a loop living only inside it could not run on a machine without the Graph SDK and SC-004 could not be proven at all. The entry script is now a thin wrapper and what ships is what is tested. The invalid-config corpus is generated by a committed script, with the generated fixtures committed too, so a reviewer sees the fixture in the diff. Defects found by running the code, not by reading it Group and role ID lists were double-wrapped: @(Get-PersonaGroupIdPage ...) around a comma-returned array collapsed every membership list into one bogus space-joined entry. That is a silent false non-match, exactly what FR-013 exists to prevent. A 403 whose status appears only in the exception message parsed as $null, which the retry policy treats as a transport error - five requests per account against a tenant already refusing. Status extraction now falls back to the message text, bounded to 400-599. The sanitization scan walked tracked files only, so it covered 34 of 156 files and none of this phase's code. It now scans untracked non-ignored files too, and a negative control confirms it catches a planted leak. Test-Json reports one error per violating location, not first-failure-only as the V-5a draft claimed. Record and pin corrected. Enforcement remains blocked on the V-4 security sign-off. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-20 21:48:19 -04:00
parent c59c85dd55
commit cdc6bb33d3
124 changed files with 16638 additions and 199 deletions
@@ -0,0 +1,141 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+<#
+    US9: condition tracing is available only when explicitly enabled.
+
+    The default matters more than the feature. Tracing widens what an audit record
+    contains beyond the UPN and Object ID that are approved by default (Principle V),
+    so a trace that appeared without being asked for would quietly change what the log
+    holds - and nobody reviews a log for fields they did not know were there.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
+    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }
+
+    $script:target = 'extension_<EXTENSION-APP-ID>_<PERSONA>'
+
+    $script:rules = @(
+        [pscustomobject]@{
+            id = 'RULE-0010-GUEST'; name = 'Guests'; enabled = $true; priority = 10; persona = 'Guest'
+            match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'UserType'; operator = 'equals'; value = 'Guest' }) }
+        }
+        [pscustomobject]@{
+            id = 'RULE-0900-EMPLOYEE'; name = 'Employees'; enabled = $true; priority = 900; persona = 'Employee'
+            match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'isNotNull' }) }
+        }
+    )
+
+    $script:record = New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' `
+        -UserPrincipalName 'alex@example.invalid' -UserType 'Member' `
+        -Properties @{ Department = 'Finance' } -StoredPersona 'Employee' `
+        -Membership (New-PersonaMembershipRecord -AllRetrieved)
+}
+
+Describe 'Trace gating on the decision result' {
+
+    It 'leaves ConditionTrace null by default' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules
+
+        $result.ConditionTrace | Should -BeNullOrEmpty
+    }
+
+    It 'populates ConditionTrace when tracing is requested' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules -IncludeTrace
+
+        $result.ConditionTrace | Should -Not -BeNullOrEmpty
+        $result.ConditionTrace.Count | Should -Be $result.RulesEvaluated
+    }
+
+    It 'records the per-rule result and priority in the trace' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules -IncludeTrace
+
+        $result.ConditionTrace[0].RuleId | Should -Be 'RULE-0010-GUEST'
+        $result.ConditionTrace[0].Priority | Should -Be 10
+        $result.ConditionTrace[0].Result | Should -Be 'False'
+
+        $result.ConditionTrace[1].RuleId | Should -Be 'RULE-0900-EMPLOYEE'
+        $result.ConditionTrace[1].Result | Should -Be 'True'
+    }
+
+    It 'does not change the decision when tracing is on' {
+        # Tracing is diagnostic. If it could alter an outcome, a debug run would stop
+        # being evidence about the real one.
+        $plain = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules
+        $traced = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules -IncludeTrace
+
+        $traced.Outcome | Should -Be $plain.Outcome
+        $traced.MatchedRuleId | Should -Be $plain.MatchedRuleId
+        $traced.CalculatedPersona | Should -Be $plain.CalculatedPersona
+        $traced.RulesEvaluated | Should -Be $plain.RulesEvaluated
+    }
+}
+
+Describe 'Trace gating on the audit record' {
+
+    It 'omits conditionTrace when tracing is off' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules -IncludeTrace
+        $result.Action = 'Unchanged'
+
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result $result
+
+        # The result carries a trace, but the record was not asked to include it.
+        # Both gates have to be open.
+        $record.Contains('conditionTrace') | Should -BeFalse
+    }
+
+    It 'includes conditionTrace when both the result and the record are traced' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules -IncludeTrace
+        $result.Action = 'Unchanged'
+
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result $result -IncludeTrace
+
+        $record.Contains('conditionTrace') | Should -BeTrue
+        $record['conditionTrace'].Count | Should -Be 2
+        $record['conditionTrace'][0]['ruleId'] | Should -Be 'RULE-0010-GUEST'
+    }
+
+    It 'omits conditionTrace when tracing was requested but the result carries none' {
+        $result = Resolve-UserPersona -UserRecord $script:record -Rules $script:rules
+        $result.Action = 'Unchanged'
+
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result $result -IncludeTrace
+
+        $record.Contains('conditionTrace') | Should -BeFalse
+    }
+}
+
+Describe 'Trace gating across a run' {
+
+    BeforeEach {
+        Mock Write-Host { }
+        Mock Get-PersonaUsers { @(New-TestPopulation -Count 6 -TargetAttribute $script:target) }
+    }
+
+    It 'emits no condition values anywhere when tracing is off' {
+        $info = $null
+        $null = Invoke-PersonaEngineRun -Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
+            -TargetAttribute $script:target -Context (New-TestAuditContext) `
+            -AuditParameters @{ Destination = 'stream' } -InformationVariable info
+
+        foreach ($event in (Get-CapturedAuditRecord -Captured $info -RecordType 'UserEvent')) {
+            $event.Contains('conditionTrace') | Should -BeFalse
+        }
+    }
+
+    It 'emits a trace on every user event when tracing is on' {
+        $info = $null
+        $null = Invoke-PersonaEngineRun -Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
+            -TargetAttribute $script:target -Context (New-TestAuditContext) `
+            -AuditParameters @{ Destination = 'stream' } -Tracing -InformationVariable info
+
+        $events = Get-CapturedAuditRecord -Captured $info -RecordType 'UserEvent'
+        $events.Count | Should -BeGreaterThan 0
+
+        foreach ($event in $events) {
+            $event.Contains('conditionTrace') | Should -BeTrue
+            $event['conditionTrace'].Count | Should -BeGreaterThan 0
+        }
+    }
+}