dave
cdc6bb33d3
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>
125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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`
|
|
|
|
```text
|
|
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`
|
|
|
|
```text
|
|
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`
|
|
|
|
```text
|
|
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).
|
|
|
|
```powershell
|
|
# 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`
|
|
|
|
```text
|
|
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.
|