From 1a6989a9bb8a45178bdc3c5c7a9fd8a64b1f67ba Mon Sep 17 00:00:00 2001
From: Dev <dev@sharepoint-toolbox.local>
Date: Tue, 7 Apr 2026 12:37:26 +0200
Subject: [PATCH] feat(07-01): add IUserAccessAuditService and
 IGraphUserSearchService interfaces

- IUserAccessAuditService.AuditUsersAsync: scan sites and filter by user logins
- IGraphUserSearchService.SearchUsersAsync: Graph API people-picker autocomplete
- GraphUserResult record: DisplayName, UserPrincipalName, Mail
---
 .../Services/IGraphUserSearchService.cs       | 27 +++++++++++++++++
 .../Services/IUserAccessAuditService.cs       | 30 +++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 SharepointToolbox/Services/IGraphUserSearchService.cs
 create mode 100644 SharepointToolbox/Services/IUserAccessAuditService.cs

diff --git a/SharepointToolbox/Services/IGraphUserSearchService.cs b/SharepointToolbox/Services/IGraphUserSearchService.cs
new file mode 100644
index 0000000..b6e7638
--- /dev/null
+++ b/SharepointToolbox/Services/IGraphUserSearchService.cs
@@ -0,0 +1,27 @@
+namespace SharepointToolbox.Services;
+
+/// <summary>
+/// Searches tenant users via Microsoft Graph API for the people-picker autocomplete.
+/// </summary>
+public interface IGraphUserSearchService
+{
+    /// <summary>
+    /// Searches for users in the tenant whose display name or email matches the query.
+    /// Returns up to <paramref name="maxResults"/> matches.
+    /// </summary>
+    /// <param name="clientId">The Azure AD app client ID for Graph authentication.</param>
+    /// <param name="query">Partial name or email to search for.</param>
+    /// <param name="maxResults">Maximum number of results to return (default 10).</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>List of (DisplayName, Email/UPN) tuples.</returns>
+    Task<IReadOnlyList<GraphUserResult>> SearchUsersAsync(
+        string clientId,
+        string query,
+        int maxResults = 10,
+        CancellationToken ct = default);
+}
+
+/// <summary>
+/// Represents a user returned by the Graph API people search.
+/// </summary>
+public record GraphUserResult(string DisplayName, string UserPrincipalName, string? Mail);
diff --git a/SharepointToolbox/Services/IUserAccessAuditService.cs b/SharepointToolbox/Services/IUserAccessAuditService.cs
new file mode 100644
index 0000000..758168d
--- /dev/null
+++ b/SharepointToolbox/Services/IUserAccessAuditService.cs
@@ -0,0 +1,30 @@
+using SharepointToolbox.Core.Models;
+
+namespace SharepointToolbox.Services;
+
+/// <summary>
+/// Scans permissions across selected sites and filters results to show
+/// only what specific user(s) can access.
+/// </summary>
+public interface IUserAccessAuditService
+{
+    /// <summary>
+    /// Scans all selected sites for permissions, then filters results to entries
+    /// matching the specified user logins. Returns a flat list of UserAccessEntry
+    /// records suitable for DataGrid binding and export.
+    /// </summary>
+    /// <param name="sessionManager">Session manager for creating authenticated contexts.</param>
+    /// <param name="targetUserLogins">Login names (emails) of users to audit.</param>
+    /// <param name="sites">Sites to scan.</param>
+    /// <param name="options">Scan depth options (inherited, folders, subsites).</param>
+    /// <param name="progress">Progress reporter.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Flat list of access entries for the target users.</returns>
+    Task<IReadOnlyList<UserAccessEntry>> AuditUsersAsync(
+        ISessionManager sessionManager,
+        IReadOnlyList<string> targetUserLogins,
+        IReadOnlyList<SiteInfo> sites,
+        ScanOptions options,
+        IProgress<OperationProgress> progress,
+        CancellationToken ct);
+}