dave/personaEngine2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Dave
2026-08-20 21:48:19 -04:00
parent c59c85dd55
commit cdc6bb33d3
124 changed files with 16638 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Safety/WriteBody.Tests.ps1
+128
View File
@@ -0,0 +1,128 @@
#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
<#
SC-005: every write body has exactly one key, equal to engine.targetAttribute.
This is the assertion that bounds the blast radius. OTD-003 records that Graph
application permissions have no per-property scope: whatever this engine can write
to the persona attribute, it could equally write to any other user property. The
directory will not stop a body with a second key, so this test is the thing that
does.
#>
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:approved = @($script:target)
}
Describe 'Write body construction (SC-005)' -Tag 'Safety' {
It 'produces a body with exactly one key' {
$body = New-PersonaWriteBody -AttributeName $target -Value 'Employee' `
-TargetAttribute $target -ApprovedWritableAttributes $approved
$body.Count | Should -Be 1
}
It 'names that key exactly the target attribute' {
$body = New-PersonaWriteBody -AttributeName $target -Value 'Employee' `
-TargetAttribute $target -ApprovedWritableAttributes $approved
@($body.Keys)[0] | Should -BeExactly $target
}
It 'carries the calculated value unchanged' {
$body = New-PersonaWriteBody -AttributeName $target -Value 'Tier0-Admin' `
-TargetAttribute $target -ApprovedWritableAttributes $approved
$body[$target] | Should -BeExactly 'Tier0-Admin'
}
It 'permits an empty value, which clears the attribute' {
# Clearing is a legitimate outcome when a rule set stops matching an account.
# It must go through the same single-key path as any other write.
$body = New-PersonaWriteBody -AttributeName $target -Value '' `
-TargetAttribute $target -ApprovedWritableAttributes $approved
$body.Count | Should -Be 1
$body[$target] | Should -Be ''
}
}
Describe 'Every body issued during a run has exactly one key' -Tag 'Safety' {
It 'holds across a full enforcing population' {
# The unit test above proves the builder is correct. This proves the run loop
# actually uses it, on every account, with no other path to a PATCH.
$script:captured = [System.Collections.Generic.List[object]]::new()
Mock Write-Host { }
Mock Get-PersonaUsers { @(New-TestPopulation -Count 20 -TargetAttribute $script:target) }
Mock Invoke-PersonaGraphRequest {
if ($Method -eq 'PATCH') { $script:captured.Add($Body) }
@{}
}
$outcome = Invoke-PersonaEngineRun `
-Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
-TargetAttribute $script:target -Context (New-TestAuditContext -Mode 'Enforce') `
-IsEnforcing -ShouldProcessGate { param($t, $d) $true }
$script:captured.Count | Should -BeGreaterThan 0
$script:captured.Count | Should -Be $outcome.Counters.Updated
foreach ($body in $script:captured) {
$body.Count | Should -Be 1
@($body.Keys)[0] | Should -BeExactly $script:target
}
}
It 'issues a PATCH and nothing else as a write method' {
$script:methods = [System.Collections.Generic.List[string]]::new()
Mock Write-Host { }
Mock Get-PersonaUsers { @(New-TestPopulation -Count 10 -TargetAttribute $script:target) }
Mock Invoke-PersonaGraphRequest {
$script:methods.Add($Method)
@{}
}
$null = Invoke-PersonaEngineRun `
-Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
-TargetAttribute $script:target -Context (New-TestAuditContext -Mode 'Enforce') `
-IsEnforcing -ShouldProcessGate { param($t, $d) $true }
# No PUT and no DELETE: a PUT would replace the whole user object, and there
# is no circumstance in which this engine removes one.
$script:methods | Should -Not -Contain 'PUT'
$script:methods | Should -Not -Contain 'DELETE'
$script:methods | Should -Not -Contain 'POST'
$script:methods | Should -Contain 'PATCH'
}
}
Describe 'New-PersonaWriteBody is the only construction path' -Tag 'Safety' {
It 'is the only source file that builds a PATCH body' {
# A second construction site would make SC-005 a property of a convention
# rather than of a testable function.
$sources = Get-ChildItem -Path (Join-Path $repoRoot 'src') -Filter '*.ps1' -Recurse -File
$offenders = foreach ($file in $sources) {
if ($file.Name -eq 'New-PersonaWriteBody.ps1') { continue }
$text = Get-Content -LiteralPath $file.FullName -Raw
if ($text -match "Method\s*=?\s*'PATCH'" -and $text -notmatch 'New-PersonaWriteBody') {
# Invoke-PersonaGraphRequest declares PATCH in a ValidateSet; it does
# not construct a body.
if ($file.Name -ne 'Invoke-PersonaGraphRequest.ps1') { $file.Name }
}
}
$offenders | Should -BeNullOrEmpty
}
}