Files

T

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

4.7 KiB

Raw Blame History

Contract: Directory Data Provider

The only component permitted to talk to Microsoft Graph. Implements OTD-002, OTD-004, and OTD-007. Everything below the normalization boundary is invisible to the rule engine (Principle IV).

Transport: Invoke-MgGraphRequest from Microsoft.Graph.Authentication (OTD-004). No resource-specific SDK modules.

Authentication (FR-003)

Function	Environment	Mechanism
`Connect-PersonaGraphManagedIdentity`	Azure Automation	`Connect-MgGraph -Identity`
`Connect-PersonaGraphInteractive`	Local development	`Connect-MgGraph -Scopes <read scopes>`

Both return an opaque connection handle. No token, header, or secret is ever returned to a caller, logged, or written to an audit record.

Permissions (OTD-002)

Function	Application permission
`Get-PersonaUsers`	`User.Read.All` (or `User.ReadWrite.All` for the enforcement identity)
`Get-PersonaGroupMembership`	`GroupMember.Read.All`
`Get-PersonaDirectoryRoles`	`RoleManagement.Read.Directory`
`Set-UserPersonaAttribute`	`User.ReadWrite.All`

Directory.Read.All is prohibited — materially broader than the three read permissions combined.

Read operations

`Get-PersonaUsers`

GET /v1.0/users?$select=<fields>&$top=999

$select carries the FR-005 baseline (id, userPrincipalName, displayName, userType, accountEnabled, companyName, jobTitle, department) plus the configured target attribute and any property referenced by an enabled rule. Unused properties are not requested.
The persona directory extension is selected by its full name, extension_<EXTENSION-APP-ID>_<APPROVED-PERSONA-ATTRIBUTE-NAME>.
Pagination follows @odata.nextLink until absent (FR-004). A truncated enumeration MUST raise — never return a partial population as if complete.
-UserObjectId switches to GET /v1.0/users/{id}?$select=....

`Get-PersonaGroupMembership`

GET /v1.0/users/{id}/memberOf            # direct
GET /v1.0/users/{id}/transitiveMemberOf  # transitive

Mode comes from the condition, falling back to engine.defaultMembershipMode (RE-007).

Return contract: always a MembershipRecord. On failure it returns a record with RetrievalSucceeded = $false and a FailureReason — it MUST NOT return an empty list, and MUST NOT throw past the per-user boundary. This single behaviour is what makes FR-013 work: unknown membership becomes EvaluationError, never a false non-match.

`Get-PersonaDirectoryRoles`

GET /v1.0/roleManagement/directory/roleAssignments?$filter=principalId eq '<id>'

Eligible (PIM) assignments are out of scope for v1 unless authorization is confirmed.

Caching

Group and role data reusable across users is cached for the run's lifetime (NFR-002). The cache is keyed by group or role Object ID and is never persisted between runs — a stale cache would make results depend on run history, breaking Principle I.

Write operation

`New-PersonaWriteBody`

The only function permitted to construct a write body (OTD-003 control 3).

# Returns exactly one key.
@{ "<engine.targetAttribute>" = "<CalculatedPersona>" }

Contract:

Throws if the attribute name is not engine.targetAttribute.
Throws if the attribute is absent from approvedWritableAttributes.
Returns a hashtable whose Count is exactly 1. Tests assert on this directly (SC-005).

`Set-UserPersonaAttribute`

PATCH /v1.0/users/{id}
Content-Type: application/json

<body from New-PersonaWriteBody>

Callable only when ShouldProcess returned $true. Under -WhatIf this function is not reached — the caller does not construct a request at all (SC-004). Preview mode is an absence of a call, not a suppressed call.
A failure returns UpdateFailed for that user and does not terminate the run.

Retry policy (OTD-007)

Aspect	Value
Retryable	429, 500, 502, 503, 504, transport timeout
Never retried	400, 401, 403, 404, 409
`Retry-After`	Honoured when present; overrides computed backoff
Attempts	Max 5
Backoff	Exponential from 1s, full jitter, per-delay cap 60s
Logging	Attempt number, status code, and delay on every retry

Exhausted retries on required data produce EvaluationError for the affected user (FR-013). Exhausted retries during enumeration are fatal (exit code 3).

Prohibited in this layer

Logging tokens, Authorization headers, or full response bodies (Principle V).
Returning raw Graph objects past ConvertTo-Persona*Record.
Any reference to rule, persona, or condition concepts — this layer moves data, it does not decide.

4.7 KiB Raw Blame History