Feat: Permission Annotations

.github/agents/CIPP-Endpoint-Agent.md

@@ -150,6 +150,29 @@ A helper must let its caller tell an input problem apart from an upstream failur
   explicit `[HttpStatusCode]::BadRequest` / `NotFound` returns where you can.
 - Ask the maintainer before regenerating the spec.
 
+### Permissions
+
+Each function that calls Microsoft Graph lists the permissions those calls need in its help `.NOTES`, one line per
+operation and permission type:
+
+```
+.NOTES
+    Permission: Graph | GET /users/{id} | Delegated | User.ReadBasic.All | User.Read.All, User.ReadWrite.All
+    Permission: Exchange | Set-Mailbox | Delegated | Mail Recipients | Organization Management | only when archiving
+```
+
+Columns: API | operation | `Delegated` or `Application` | least privileged | higher privileged [| condition].
+
+- `pwsh build/tools/Update-PermissionAnnotations.ps1` writes the Graph lines from the code: the URI, method and
+  `-AsApp`, least privileged from Microsoft's permissions map and higher privileged from the Learn page. Run it after
+  changing a Graph call; CI runs it with `-Check`. `-Refresh` re-downloads Microsoft's data.
+- Write a line by hand only for what the script cannot derive: other APIs (Exchange, SharePoint, Partner Center),
+  or a Graph call whose URI is built at runtime. The script keeps those, and keeps a condition you add to a line it writes.
+- Never add a new help keyword such as `.PERMISSIONS`: an unknown keyword stops PowerShell reading the whole help block,
+  `.ROLE` and `.FUNCTIONALITY` included, and the endpoint stops routing.
+- `build-openapi.ps1` rolls the lines up through every helper and queued activity an endpoint reaches into
+  `x-cipp-permissions`, and indexes them by permission in the top-level `x-cipp-permission-index`.
+
 ---
 
 ## Tests

.github/workflows/openapi_spec.yml

@@ -6,14 +6,16 @@ on:
       - main
       - dev
     paths:
-      - 'backend/Modules/CIPPHTTP/**'
-      # entrypoints hand the body to these, and the generator follows the call
-      - 'backend/Modules/CIPPCore/**'
+      # entrypoints hand the body to CIPPCore helpers, and permissions roll up through every module
+      - 'backend/Modules/**'
       - 'backend/Config/openapi.json'
       - 'backend/Config/openapi-overrides/**'
+      - 'backend/Config/SAMManifest.json'
       # simpleColumns declarations type the list responses
       - 'frontend/src/**'
       - 'build/tools/build-openapi.ps1'
+      - 'build/tools/Update-PermissionAnnotations.ps1'
+      - 'build/tools/graph-*permissions.json'
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
   cancel-in-progress: true
@@ -29,6 +31,18 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # Each function's .NOTES lists the Graph permissions its calls need; the spec rolls them up per endpoint.
+      - name: Check the Permission lines match the Graph calls
+        shell: pwsh
+        run: |
+          try {
+            ./build/tools/Update-PermissionAnnotations.ps1 -Check
+          } catch {
+            Write-Host "::error::$($_.Exception.Message)"
+            Write-Host 'Regenerate with: pwsh build/tools/Update-PermissionAnnotations.ps1'
+            exit 1
+          }
+
       # backend/Config/openapi.json is loaded at runtime by Get-CippMcpSpec and
       # projected into the MCP tool list, so a stale committed spec ships a tool
       # contract that no longer matches the endpoints.