---
phase: 07-user-access-audit
plan: 02
subsystem: audit-engine
tags: [service, business-logic, user-access-audit, permissions, transform]
dependency_graph:
  requires: [07-01]
  provides: [UserAccessAuditService]
  affects: [07-04, 07-05, 07-06, 07-07, 07-08]
tech_stack:
  added: []
  patterns: [iterator pattern (yield return), HashSet for O(1) lookup, case-insensitive contains matching]
key_files:
  created:
    - SharepointToolbox/Services/UserAccessAuditService.cs
  modified: []
decisions:
  - "TenantProfile.ClientId set to empty string in service — session must be pre-authenticated at ViewModel level; SessionManager returns cached context by URL key without requiring ClientId again"
  - "User matching uses bidirectional contains (loginLower.Contains(target) || target.Contains(loginLower)) to handle both plain email and full SharePoint claim formats"
  - "Each permission level emits a separate UserAccessEntry row (fully denormalized) — consistent with 07-01 design decision"
metrics:
  duration_minutes: 5
  completed_date: "2026-04-07"
  tasks_completed: 1
  files_created: 1
  files_modified: 0
---

# Phase 7 Plan 02: UserAccessAuditService Implementation Summary

**One-liner:** UserAccessAuditService scans PermissionsService results across multiple sites, filters by target user logins via bidirectional contains matching, and emits fully-denormalized UserAccessEntry rows with access type classification, high-privilege detection, and external user flagging.

## What Was Built

**UserAccessAuditService.cs** — Core business logic service implementing `IUserAccessAuditService`:

1. **Multi-site loop** — Iterates sites list, builds a `TenantProfile` per site (TenantUrl = site URL), obtains a `ClientContext` via the injected `ISessionManager`, then delegates to `IPermissionsService.ScanSiteAsync` for raw permission data. Progress is reported per site.

2. **TransformEntries** — Static iterator method that splits semicolon-delimited `UserLogins`, `Users`, and `PermissionLevels` fields from each `PermissionEntry`. For each user/level combination that matches a target login, yields a `UserAccessEntry` record. Uses `yield return` for lazy evaluation.

3. **User matching** — Case-insensitive bidirectional contains: `loginLower.Contains(target) || target.Contains(loginLower)`. Handles both plain email addresses and full SharePoint claim format (`i:0#.f|membership|alice@contoso.com`).

4. **ClassifyAccessType** — Maps `HasUniquePermissions` + `GrantedThrough` to `AccessType` enum: `!HasUniquePermissions` → Inherited; `GrantedThrough` starts with "SharePoint Group:" → Group; else Direct.

5. **HighPrivilegeLevels** — Static `HashSet<string>` (case-insensitive) containing "Full Control" and "Site Collection Administrator". O(1) lookup per entry.

## Tasks

| # | Task | Status | Commit |
|---|------|--------|--------|
| 1 | Implement UserAccessAuditService | Done | 44b238e |

## Decisions Made

1. **ClientId empty in service** — `TenantProfile.ClientId` is set to `string.Empty` when constructing per-site profiles. `SessionManager` validates ClientId only when creating a new context. Since the user authenticates at the ViewModel layer before invoking the service, the session is already cached and returned by URL key without re-checking ClientId.

2. **Bidirectional contains matching** — The target login could be a short email ("alice@contoso.com") while the PermissionEntry stores the full claim ("i:0#.f|membership|alice@contoso.com"), or vice versa. Bidirectional contains handles both cases without requiring callers to normalize their input format.

3. **Fully denormalized output** — Consistent with the 07-01 decision: one row per user + object + permission level. A single PermissionEntry with 2 users and 3 permission levels emits up to 6 UserAccessEntry rows.

## Deviations from Plan

None — plan executed exactly as written.

## Verification

- `dotnet build SharepointToolbox/SharepointToolbox.csproj` — 0 errors, 0 warnings
- UserAccessAuditService implements IUserAccessAuditService interface
- TransformEntries splits semicolon-delimited logins/names/levels correctly
- ClassifyAccessType maps HasUniquePermissions + GrantedThrough to AccessType enum
- HighPrivilegeLevels HashSet contains "Full Control" and "Site Collection Administrator"

## Self-Check: PASSED

Files confirmed present:
- FOUND: SharepointToolbox/Services/UserAccessAuditService.cs

Commits confirmed:
- FOUND: 44b238e