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/Unit/RecordContracts.Tests.ps1
+181
View File
@@ -0,0 +1,181 @@
#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
BeforeAll {
$repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
. (Join-Path $repoRoot 'src/Normalization/New-PersonaMembershipRecord.ps1')
. (Join-Path $repoRoot 'src/Normalization/New-PersonaUserRecord.ps1')
. (Join-Path $repoRoot 'src/Configuration/New-PersonaValidationFinding.ps1')
}
Describe 'New-PersonaMembershipRecord' {
Context 'retrieval flags default to unretrieved' {
It 'defaults every facet to $false so an unset flag means unknown, never "not a member"' {
# The safety-critical default. If any of these flip, a failed group
# lookup satisfies notMemberOf and privileged accounts get misclassified.
$record = New-PersonaMembershipRecord
$record.DirectRetrieved | Should -BeFalse
$record.TransitiveRetrieved | Should -BeFalse
$record.RolesRetrieved | Should -BeFalse
}
It 'sets a facet only when explicitly requested' {
$record = New-PersonaMembershipRecord -DirectRetrieved
$record.DirectRetrieved | Should -BeTrue
$record.TransitiveRetrieved | Should -BeFalse
}
It 'AllRetrieved sets every facet' {
$record = New-PersonaMembershipRecord -AllRetrieved
$record.DirectRetrieved | Should -BeTrue
$record.TransitiveRetrieved | Should -BeTrue
$record.RolesRetrieved | Should -BeTrue
}
}
Context 'independent facets (RE-007)' {
It 'carries direct and transitive membership simultaneously' {
# The reason this record has three facets rather than one mode: a rule
# set may ask for direct membership in one rule and transitive in
# another, and a single-mode record cannot answer both.
$record = New-PersonaMembershipRecord `
-DirectGroupObjectIds @('00000000-0000-0000-0000-0000000000a0') `
-TransitiveGroupObjectIds @('00000000-0000-0000-0000-0000000000a0', '00000000-0000-0000-0000-0000000000b0') `
-AllRetrieved
$record.DirectGroupObjectIds | Should -HaveCount 1
$record.TransitiveGroupObjectIds | Should -HaveCount 2
}
It 'contains a failure to the facet that failed' {
# A transitive lookup that times out must not make direct-membership
# conditions unevaluable — otherwise one slow endpoint becomes a
# tenant-wide outage.
$record = New-PersonaMembershipRecord -DirectRetrieved -RolesRetrieved -TransitiveFailureReason 'Graph 503'
$record.DirectRetrieved | Should -BeTrue
$record.RolesRetrieved | Should -BeTrue
$record.TransitiveRetrieved | Should -BeFalse
$record.TransitiveFailureReason | Should -Be 'Graph 503'
}
}
Context 'shape' {
It 'always returns arrays, never $null, for the identifier collections' {
$record = New-PersonaMembershipRecord -AllRetrieved
, $record.DirectGroupObjectIds | Should -BeOfType [System.Array]
, $record.TransitiveGroupObjectIds | Should -BeOfType [System.Array]
, $record.DirectoryRoleIds | Should -BeOfType [System.Array]
}
It 'refuses to be both retrieved and failed on the same facet' {
{ New-PersonaMembershipRecord -DirectRetrieved -DirectFailureReason 'boom' } |
Should -Throw '*cannot be both*'
}
It 'refuses AllRetrieved alongside any failure reason' {
{ New-PersonaMembershipRecord -AllRetrieved -RolesFailureReason 'boom' } |
Should -Throw '*cannot be both*'
}
}
}
Describe 'New-PersonaUserRecord' {
Context 'required identity fields' {
It 'requires a non-empty AccountObjectId' {
{ New-PersonaUserRecord -AccountObjectId '' -UserPrincipalName 'a@example.invalid' } |
Should -Throw
}
It 'requires a non-empty UserPrincipalName' {
{ New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName '' } |
Should -Throw
}
}
Context 'property bag' {
BeforeAll {
$script:record = New-PersonaUserRecord `
-AccountObjectId '00000000-0000-0000-0000-000000000101' `
-UserPrincipalName 'alex.employee@example.invalid' `
-UserType 'Member' `
-Properties @{ Department = 'Finance'; CompanyName = $null }
}
It 'looks up properties case-insensitively (RE-006)' {
$record.Properties['department'] | Should -Be 'Finance'
$record.Properties['DEPARTMENT'] | Should -Be 'Finance'
}
It 'returns $null for an absent property rather than throwing (FR-012)' {
$record.Properties['NoSuchProperty'] | Should -BeNullOrEmpty
}
It 'preserves an explicit null value' {
$record.Properties['CompanyName'] | Should -BeNullOrEmpty
}
It 'exposes intrinsic fields as addressable properties' {
$record.Properties['UserPrincipalName'] | Should -Be 'alex.employee@example.invalid'
$record.Properties['UserType'] | Should -Be 'Member'
$record.Properties['AccountEnabled'] | Should -Be $true
}
It 'lets an explicit property override an intrinsic default' {
$overridden = New-PersonaUserRecord `
-AccountObjectId '00000000-0000-0000-0000-000000000101' `
-UserPrincipalName 'a@example.invalid' `
-Properties @{ UserType = 'Overridden' }
$overridden.Properties['UserType'] | Should -Be 'Overridden'
}
}
Context 'membership default' {
It 'never leaves Membership null' {
$record = New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName 'a@example.invalid'
$record.Membership | Should -Not -BeNullOrEmpty
}
It 'defaults to a fully unretrieved record so membership conditions yield Unknown' {
# An absent lookup is unknown, never "member of nothing". A rule set
# with no membership conditions never consults this; one that does must
# get EvaluationError rather than a fabricated non-match.
$record = New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName 'a@example.invalid'
$record.Membership.DirectRetrieved | Should -BeFalse
$record.Membership.TransitiveRetrieved | Should -BeFalse
$record.Membership.RolesRetrieved | Should -BeFalse
}
}
}
Describe 'New-PersonaValidationFinding' {
It 'derives the layer from the code namespace' {
(New-PersonaValidationFinding -Severity Error -Code 'PE-SEM-001' -Location 'rules[0]' -Description 'd' -SuggestedResolution 'r').Layer |
Should -Be 'Semantic'
(New-PersonaValidationFinding -Severity Warning -Code 'PE-SAF-001' -Location 'engine' -Description 'd' -SuggestedResolution 'r').Layer |
Should -Be 'Safety'
}
It 'rejects a malformed finding code' {
{ New-PersonaValidationFinding -Severity Error -Code 'BAD-001' -Location 'x' -Description 'd' -SuggestedResolution 'r' } |
Should -Throw
}
It 'requires a suggested resolution' {
{ New-PersonaValidationFinding -Severity Error -Code 'PE-SEM-001' -Location 'x' -Description 'd' -SuggestedResolution '' } |
Should -Throw
}
It 'rejects an unrecognized severity' {
{ New-PersonaValidationFinding -Severity Critical -Code 'PE-SEM-001' -Location 'x' -Description 'd' -SuggestedResolution 'r' } |
Should -Throw
}
}