#Requires -Version 7.0
# PIM Manager 3.0.70 -- Grant-PimEnginePermissions.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: _pimenginepermissions.ps1, _pimloopbackanswer.ps1, _pimscriptdoc.ps1)


<#
.SYNOPSIS
    Give the PIM Manager engine identity the Microsoft Graph (and other API) application permissions and Azure role
    assignments it is missing. Run once, as a Global Administrator (or Privileged Role Administrator for the
    application permissions; Owner / User Access Administrator at the scope for an Azure role). -WhatIf shows every
    grant first and changes nothing.

.DESCRIPTION
    PIM Manager shows this command with your environment's exact values (Overview > permission check, and the Get
    Started step "Engine permissions"): the page itself is read-only on purpose -- an identity that can grant
    permissions could give itself anything.

    No PowerShell modules: plain REST + .NET, PowerShell 7. You sign in in the browser
    (Microsoft Edge is opened; the default browser when Edge is not installed). Azure role assignments ask for a second,
    quick sign-in to Azure.

    The script is idempotent: what the engine identity already holds is reported and left alone. Every grant is read
    back. At the end it prints, per permission: granted / already there / refused (with the reason), and exits 1 when
    anything was refused. A new grant reaches the engine's token within about 30 minutes; then press
    "Verify permissions" in PIM Manager.

    Download: Invoke-WebRequest https://invardia.com/support/pim/Grant-PimEnginePermissions.ps1 -OutFile Grant-PimEnginePermissions.ps1

.PARAMETER TenantId
    Your tenant id. The sign-in is refused when it lands in another tenant.
.PARAMETER EngineObjectId
    Object id of the engine identity's service principal (shown in PIM Manager).
.PARAMETER GraphPermissions
    Microsoft Graph application permissions, e.g. 'Group.ReadWrite.All','RoleManagement.ReadWrite.Directory'.
.PARAMETER AppRoles
    Application permissions of other APIs as '<permission>@<API application id>',
    e.g. 'Exchange.ManageAsApp@00000002-0000-0ff1-ce00-000000000000'.
.PARAMETER AzureRoleAssignments
    Azure roles as '<role name or role definition id>@<scope>',
    e.g. 'User Access Administrator@/providers/Microsoft.Management/managementGroups/<tenant id>'.
.PARAMETER UseEdge
    $true (default): open Microsoft Edge for the sign-in. $false: the default browser.
.PARAMETER GraphAccessToken
    Automation: a Microsoft Graph token (delegated AppRoleAssignment.ReadWrite.All + Application.Read.All) instead of
    the browser sign-in.
.PARAMETER ArmAccessToken
    Automation: an Azure Resource Manager token instead of the second browser sign-in.
.PARAMETER PlanOnly
    Read and report what would be granted; change nothing. (-WhatIf does the same and prints each grant as a
    "What if:" line.)
.PARAMETER PassThru
    Also return the result rows as objects.

.EXAMPLE
    .\Grant-PimEnginePermissions.ps1 -TenantId '<tenant id>' -EngineObjectId '<object id>' -GraphPermissions 'Group.ReadWrite.All','User.ReadWrite.All'
.EXAMPLE
    .\Grant-PimEnginePermissions.ps1 -TenantId '<tenant id>' -EngineObjectId '<object id>' -AzureRoleAssignments 'User Access Administrator@/providers/Microsoft.Management/managementGroups/<tenant id>'
.EXAMPLE
    .\Grant-PimEnginePermissions.ps1 -TenantId '<tenant id>' -EngineObjectId '<object id>' -AzureRoleAssignments 'Reader@/providers/Microsoft.Management/managementGroups/<tenant id>'
    Reader (read-only) at the tenant root management group -- what Discovery needs to see Azure. The install grants it by
    default; run this when the installing account could not. Add
    ,'User Access Administrator@/providers/Microsoft.Management/managementGroups/<tenant id>' only when the engine must
    assign the Azure resource roles you delegate (optional).
.EXAMPLE
    .\Grant-PimEnginePermissions.ps1 -TenantId '<tenant id>' -EngineObjectId '<object id>' -GraphPermissions 'Group.ReadWrite.All' -WhatIf
    Signs in and reads, then prints what it would grant ("What if: ...") -- nothing is changed.

.NOTES
    Requirements:
      PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
      Role: Privileged Role Administrator (Microsoft Entra) for the application permissions; for an Azure role, User
            Access Administrator or Owner at that role's scope (only with -AzureRoleAssignments).
      Hosts: login.microsoftonline.com, graph.microsoft.com, management.azure.com

    PERMISSIONS AND CHANGES (from Grant-PimEnginePermissions.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Grant-PimEnginePermissions/)
    The person running it needs:
      - Privileged Role Administrator [entraRole, tenant] -- Granting an application permission (an app role assignment) to a service principal needs a Privileged Role Administrator or a Global Administrator. Only needed for -GraphPermissions / -AppRoles.
      - User Access Administrator [azureRbac, each scope in -AzureRoleAssignments (for the tenant root: the root management group); Owner works too] -- Creating an Azure role assignment needs User Access Administrator or Owner at that scope. At the tenant root a Global Administrator first turns on 'Access management for Azure resources' (Microsoft Entra ID > Properties). Only needed for -AzureRoleAssignments.
      - delegated Microsoft Graph scopes AppRoleAssignment.ReadWrite.All and Application.Read.All [other, the browser sign-in (first-party public client 'Microsoft Graph Command Line Tools')] -- What the browser sign-in asks for: read the engine identity and the API's permissions, and create the app role assignment. No PowerShell module, no certificate, no secret.
      - delegated Azure Resource Manager access (user_impersonation) [other, the second browser sign-in (first-party public client 'Microsoft Azure PowerShell'), only for Azure roles] -- Reads role definitions and the engine's role assignments, and creates the missing assignment as you.
    What it creates, changes or grants:
      - grant application permission for the engine identity: an app role assignment (POST servicePrincipals/{API}/appRoleAssignedTo) for each name in -GraphPermissions (Microsoft Graph, e.g. Group.ReadWrite.All) and -AppRoles (another API, as <permission>@<API application id>) (Microsoft Graph): each application permission you pass -- PIM Manager's command names exactly the ones its permission check found missing @ tenant (application permissions apply tenant-wide) -- The engine applies the access you define in PIM Manager through these APIs; without the permission that part of the engine fails. Undo: Entra admin center > Enterprise applications > the engine identity > Permissions > remove the permission (or DELETE servicePrincipals/{engine}/appRoleAssignments/{id}).
      - grant Azure role assignment for the engine identity (Microsoft.Authorization/roleAssignments, principalType ServicePrincipal) for each '<role>@<scope>' in -AzureRoleAssignments (Azure Resource Manager): the Azure role you pass, by name or role definition id: Reader (what PIM Manager asks for at the tenant root, so discovery can see Azure), optionally User Access Administrator (only when the engine must assign the Azure resource roles you delegate); Owner, Contributor and Role Based Access Control Administrator are also recognised by name, any other name is looked up at the scope @ the scope you pass: the tenant root management group, a management group, a subscription or a resource group -- Discovery reads Azure with Reader; assigning delegated Azure resource roles needs User Access Administrator. PIM Manager never asks for Owner or Contributor. Undo: Azure portal > the scope > Access control (IAM) > Role assignments > remove the engine identity's assignment.
    -WhatIf: Signs in and reads, prints the plan (already there / would grant / refused per permission), then one "What if:" line per grant: the application permission and the API, or the Azure role and its scope. Nothing is granted.
    Undo: Remove each app role assignment from the engine identity (Entra admin center > Enterprise applications > the engine identity > Permissions) and each Azure role assignment (Access control (IAM) at the scope). The script creates nothing else.

.LINK
    https://invardia.com/docs/pim/scripts/Grant-PimEnginePermissions/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [string]$TenantId,
    [Parameter(Mandatory)][string]$EngineObjectId,
    [string[]]$GraphPermissions = @(),
    [string[]]$AppRoles = @(),
    [string[]]$AzureRoleAssignments = @(),
    [bool]$UseEdge = $true,
    [string]$GraphAccessToken,
    [string]$ArmAccessToken,
    [switch]$PlanOnly,
    [switch]$PassThru
)
$ErrorActionPreference = 'Stop'
# ===== BEGIN inlined helper: _PimEnginePermissions.ps1 =====
# _PimEnginePermissions.ps1 -- the pieces behind Grant-PimEnginePermissions.ps1: browser sign-in, one REST seam for
# Microsoft Graph and Azure Resource Manager, the pure request builders, and the grant itself. Dot-source it; it defines
# functions only (no side effects on load).
#
# NO MODULES (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): plain Invoke-RestMethod + .NET.
# Sign-in is auth code + PKCE on a localhost loopback in the browser (Edge launched explicitly, the default browser when
# Edge is missing) -- the pattern proven by the PIM Activator deploy scripts:
#   * Microsoft Graph: the first-party "Microsoft Graph Command Line Tools" public client.
#   * Azure Resource Manager (only when Azure role assignments are asked for): the first-party "Microsoft Azure
#     PowerShell" public client, which is pre-authorized for Azure Resource Manager in every tenant.
# Nothing from the engine tree is loaded: the script is published as ONE standalone file at
# https://invardia.com/support/pim/Grant-PimEnginePermissions.ps1 (tools/setup/Build-PimSupportScripts.ps1 inlines this).

# ---- constants --------------------------------------------------------------------------------------------------------
function Get-PimEpGraphCliClientId { '14d82eec-204b-4c2f-b7e8-296a70dab67e' }      # Microsoft Graph Command Line Tools
function Get-PimEpAzurePowerShellClientId { '1950a258-227b-4e31-a9cf-717495945fc2' } # Microsoft Azure PowerShell
function Get-PimEpGraphAppId { '00000003-0000-0000-c000-000000000000' }             # Microsoft Graph (the resource)
function Get-PimEpGraphScopes { @('AppRoleAssignment.ReadWrite.All', 'Application.Read.All') }
function Get-PimEpArmScope { 'https://management.azure.com/user_impersonation' }
function Get-PimEpArmApiVersion { '2022-04-01' }

# Built-in Azure roles by name (the ids are the same in every tenant); any other name is looked up at the scope.
function Get-PimEpBuiltInAzureRoles {
    @{
        'owner'                                   = '8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
        'contributor'                             = 'b24988ac-6180-42a0-ab88-20f7382dd24c'
        'reader'                                  = 'acdd72a7-3385-48ef-bd42-f606fba81ae7'
        'user access administrator'               = '18d7d88d-d35e-4fb5-a5c3-7773c20a72d9'
        'role based access control administrator' = 'f58310d9-a9f6-439a-9e8d-f62e7b41a168'
    }
}

function Test-PimEpGuid {
    param([AllowEmptyString()][string]$Text)
    "$Text" -match '^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$'
}

# VERSION at the solution root (two levels up from tools/setup); a standalone copy reads the header the build writes.
function Get-PimEpSolutionVersion {
    $f = Join-Path $PSScriptRoot '..\..\VERSION'
    if (Test-Path -LiteralPath $f) { return 'v' + (Get-Content -LiteralPath $f -TotalCount 1).Trim() }
    foreach ($self in @($PSCommandPath, $MyInvocation.ScriptName) | Where-Object { $_ }) {
        try {
            foreach ($l in @(Get-Content -LiteralPath $self -TotalCount 5 -ErrorAction Stop)) { if ($l -match '^# PIM Manager (\S+) --') { return 'v' + $Matches[1] + ' (standalone)' } }
        } catch { }
    }
    '(version not known)'
}

# ---- list + spec parsing (pure) ---------------------------------------------------------------------------------------
# A list parameter as clean items: "a,b" (one string, as `pwsh -File` passes it) and 'a','b' both become a, b.
function ConvertTo-PimEpList {
    param([object[]]$Items)
    $out = New-Object System.Collections.Generic.List[string]
    foreach ($i in @($Items)) {
        if ($null -eq $i) { continue }
        foreach ($p in ("$i" -split ',')) { $t = $p.Trim().Trim("'").Trim('"').Trim(); if ($t -and -not $out.Contains($t)) { $out.Add($t) } }
    }
    $out.ToArray()
}

# An application permission: 'Group.ReadWrite.All' (Microsoft Graph) or '<Role>@<resource appId>' (another API, e.g.
# 'Exchange.ManageAsApp@00000002-0000-0ff1-ce00-000000000000'). Returns @{ value; resourceAppId; spec }.
function ConvertTo-PimEpAppRoleSpec {
    param([Parameter(Mandatory)][string]$Spec, [string]$DefaultResourceAppId = (Get-PimEpGraphAppId))
    $s = $Spec.Trim()
    $value = $s; $res = $DefaultResourceAppId
    if ($s -match '^(?<v>[^@]+)@(?<r>[^@]+)$') { $value = $Matches['v'].Trim(); $res = $Matches['r'].Trim() }
    if (-not $value -or $value -match '\s') { throw "Not an application permission name: '$Spec'." }
    if (-not (Test-PimEpGuid $res)) { throw "The API in '$Spec' must be its application (client) id, a GUID." }
    [pscustomobject]@{ value = $value; resourceAppId = $res.ToLowerInvariant(); spec = $s }
}

# An Azure role assignment: '<role name or role definition id>@<scope>', e.g.
# 'User Access Administrator@/providers/Microsoft.Management/managementGroups/<tenant id>'. Returns
# @{ role; roleDefinitionGuid (or $null = look the name up); scope; spec }.
function ConvertTo-PimEpAzureRoleSpec {
    param([Parameter(Mandatory)][string]$Spec)
    $s = $Spec.Trim()
    $i = $s.LastIndexOf('@')
    if ($i -lt 1) { throw "An Azure role assignment is '<role>@<scope>' (e.g. 'User Access Administrator@/subscriptions/<id>'): '$Spec'." }
    $role = $s.Substring(0, $i).Trim(); $scope = $s.Substring($i + 1).Trim()
    if (-not $scope.StartsWith('/')) { throw "The scope in '$Spec' must start with '/' (e.g. /subscriptions/<id> or /providers/Microsoft.Management/managementGroups/<id>)." }
    if ($scope.Length -gt 1) { $scope = $scope.TrimEnd('/') }
    $guid = $null
    if (Test-PimEpGuid $role) { $guid = $role.ToLowerInvariant() }
    else {
        $known = Get-PimEpBuiltInAzureRoles
        $k = $role.ToLowerInvariant()
        if ($known.ContainsKey($k)) { $guid = $known[$k] }
    }
    [pscustomobject]@{ role = $role; roleDefinitionGuid = $guid; scope = $scope; spec = $s }
}

# ---- request builders (pure) ------------------------------------------------------------------------------------------
# POST /servicePrincipals/{resource}/appRoleAssignedTo -- the body that gives the engine one application permission.
function New-PimEpAppRoleAssignmentRequest {
    param([Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$ResourceId, [Parameter(Mandatory)][string]$AppRoleId)
    [pscustomobject]@{
        Method = 'POST'
        Path   = "/servicePrincipals/$ResourceId/appRoleAssignedTo"
        Body   = [ordered]@{ principalId = $PrincipalId; resourceId = $ResourceId; appRoleId = $AppRoleId }
    }
}

# The full role definition id at a scope ('/' = tenant root: no prefix).
function Get-PimEpRoleDefinitionId {
    param([Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$RoleDefinitionGuid)
    $prefix = if ($Scope -eq '/') { '' } else { $Scope.TrimEnd('/') }
    "$prefix/providers/Microsoft.Authorization/roleDefinitions/$RoleDefinitionGuid"
}

# PUT {scope}/providers/Microsoft.Authorization/roleAssignments/{new GUID} -- one Azure role for the engine.
# principalType ServicePrincipal: ARM then does not wait for directory replication of a freshly made identity.
function New-PimEpArmRoleAssignmentRequest {
    param(
        [Parameter(Mandatory)][string]$Scope,
        [Parameter(Mandatory)][string]$RoleDefinitionGuid,
        [Parameter(Mandatory)][string]$PrincipalId,
        [string]$AssignmentId = ([guid]::NewGuid().ToString())
    )
    $prefix = if ($Scope -eq '/') { '' } else { $Scope.TrimEnd('/') }
    [pscustomobject]@{
        Method       = 'PUT'
        Path         = "$prefix/providers/Microsoft.Authorization/roleAssignments/$($AssignmentId)?api-version=$(Get-PimEpArmApiVersion)"
        AssignmentId = $AssignmentId
        Body         = [ordered]@{ properties = [ordered]@{
            roleDefinitionId = (Get-PimEpRoleDefinitionId -Scope $Scope -RoleDefinitionGuid $RoleDefinitionGuid)
            principalId      = $PrincipalId
            principalType    = 'ServicePrincipal'
        } }
    }
}

# Which application permissions are still to grant. -ResourceSps maps resource appId -> its service principal
# (id, displayName, appRoles) or $null when the API has no service principal in the tenant. -Existing = the engine's
# appRoleAssignments (resourceId, appRoleId). Each item: action grant | present | unknown-role | no-resource.
function Get-PimEpAppRolePlan {
    param([object[]]$Wanted, [hashtable]$ResourceSps, [object[]]$Existing)
    $have = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
    foreach ($a in @($Existing)) { if ($a) { [void]$have.Add("$($a.resourceId)|$($a.appRoleId)") } }
    foreach ($w in @($Wanted)) {
        if (-not $w) { continue }
        $sp = $null; if ($ResourceSps -and $ResourceSps.ContainsKey($w.resourceAppId)) { $sp = $ResourceSps[$w.resourceAppId] }
        $item = [ordered]@{ value = $w.value; resourceAppId = $w.resourceAppId; resourceName = ''; resourceId = ''; appRoleId = ''; action = '' }
        if (-not $sp) { $item.action = 'no-resource'; [pscustomobject]$item; continue }
        $item.resourceName = "$($sp.displayName)"; $item.resourceId = "$($sp.id)"
        $role = @(@($sp.appRoles) | Where-Object { $_ -and "$($_.value)" -eq $w.value -and @($_.allowedMemberTypes) -contains 'Application' }) | Select-Object -First 1
        if (-not $role) { $item.action = 'unknown-role'; [pscustomobject]$item; continue }
        $item.appRoleId = "$($role.id)"
        $item.action = if ($have.Contains("$($sp.id)|$($role.id)")) { 'present' } else { 'grant' }
        [pscustomobject]$item
    }
}

# Does the engine already hold the role at (or above) the scope? -Assignments = ARM roleAssignments (properties.scope,
# properties.roleDefinitionId). Exact scope, the tenant root '/', or a parent path (a subscription above a resource
# group) count; a management-group parent is not visible from the path and is simply granted again (harmless).
function Find-PimEpArmAssignment {
    param([object[]]$Assignments, [Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$RoleDefinitionGuid)
    $target = $Scope.TrimEnd('/').ToLowerInvariant(); if (-not $target) { $target = '/' }
    foreach ($a in @($Assignments)) {
        if (-not $a -or -not $a.properties) { continue }
        $rd = "$($a.properties.roleDefinitionId)".ToLowerInvariant()
        if (-not $rd.EndsWith('/' + $RoleDefinitionGuid.ToLowerInvariant())) { continue }
        $s = "$($a.properties.scope)".TrimEnd('/').ToLowerInvariant(); if (-not $s) { $s = '/' }
        if ($s -eq $target) { return [pscustomobject]@{ how = 'exact'; scope = "$($a.properties.scope)"; id = "$($a.id)" } }
        if ($s -eq '/' -or $target.StartsWith($s + '/')) { return [pscustomobject]@{ how = 'inherited'; scope = "$($a.properties.scope)"; id = "$($a.id)" } }
    }
    $null
}

# ---- browser sign-in --------------------------------------------------------------------------------------------------
function ConvertTo-PimEpB64Url {
    param([Parameter(Mandatory)][byte[]]$Bytes)
    [Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_')
}

# The claims of a JWT (claims read only, the resource validates the token; tid / upn / exp are read). $null when not a readable JWT.
function ConvertFrom-PimEpJwtClaims {
    param([AllowEmptyString()][string]$Token)
    if (-not $Token) { return $null }
    $parts = $Token -split '\.'
    if ($parts.Count -lt 2) { return $null }
    $s = $parts[1].Replace('-', '+').Replace('_', '/')
    switch ($s.Length % 4) { 2 { $s += '==' } 3 { $s += '=' } }
    try { [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($s)) | ConvertFrom-Json } catch { $null }
}

function New-PimEpPkcePair {
    $bytes = New-Object byte[] 32
    [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
    $verifier = ConvertTo-PimEpB64Url $bytes
    $challenge = ConvertTo-PimEpB64Url ([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::ASCII.GetBytes($verifier)))
    [pscustomobject]@{ Verifier = $verifier; Challenge = $challenge }
}

# The delegated scope string: bare Graph names are qualified, OIDC basics appended once.
function Get-PimEpScopeString {
    param([Parameter(Mandatory)][string[]]$Scopes)
    $q = @($Scopes | Where-Object { $_ } | ForEach-Object { if ($_ -match '^(https?://|openid$|profile$|offline_access$)') { $_ } else { "https://graph.microsoft.com/$_" } })
    (@($q) + @('openid', 'profile', 'offline_access') | Select-Object -Unique) -join ' '
}

function New-PimEpAuthorizeUrl {
    param(
        [Parameter(Mandatory)][string]$Tenant, [Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$RedirectUri,
        [Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$State, [Parameter(Mandatory)][string]$CodeChallenge,
        [string]$LoginHint
    )
    $u = "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/authorize" +
        "?client_id=$ClientId&response_type=code&response_mode=query" +
        "&redirect_uri=$([uri]::EscapeDataString($RedirectUri))" +
        "&scope=$([uri]::EscapeDataString($Scope))&state=$State" +
        "&code_challenge=$CodeChallenge&code_challenge_method=S256"
    if ($LoginHint) { $u += "&login_hint=$([uri]::EscapeDataString($LoginHint))" } else { $u += '&prompt=select_account' }
    $u
}

function Get-PimEpEdgePath {
    @(
        $(if (${env:ProgramFiles(x86)}) { Join-Path ${env:ProgramFiles(x86)} 'Microsoft\Edge\Application\msedge.exe' }),
        $(if ($env:ProgramFiles) { Join-Path $env:ProgramFiles 'Microsoft\Edge\Application\msedge.exe' }),
        $(if ($env:LOCALAPPDATA) { Join-Path $env:LOCALAPPDATA 'Microsoft\Edge\Application\msedge.exe' })
    ) | Where-Object { $_ -and (Test-Path -LiteralPath $_) } | Select-Object -First 1
}

function Get-PimEpBrokenAuthHelp {
    @"
This computer could not complete the sign-in. Known causes, in order of likelihood:
  1. The default browser is legacy Internet Explorer: this script opens Microsoft Edge (-UseEdge `$true, the default). If you passed -UseEdge `$false, drop it.
  2. An old sign-in tab answered: close ALL browser windows and run the script again.
  3. Something blocks the local listener the browser answers to (a firewall or proxy rule for 127.0.0.1): allow it, or run the script on another computer.
  4. Bring tokens: -GraphAccessToken (scopes AppRoleAssignment.ReadWrite.All + Application.Read.All) and, for Azure roles, -ArmAccessToken.
"@
}

# Interactive sign-in: auth code + PKCE on a loopback TcpListener (works without elevation), Edge launched explicitly,
# the default browser when Edge is missing or -UseEdge is $false. Returns the token response.
function Get-PimEpInteractiveToken {
    param(
        [Parameter(Mandatory)][string]$ClientId,
        [Parameter(Mandatory)][string[]]$Scopes,
        [string]$Tenant = 'organizations',
        [bool]$UseEdge = $true,
        [string]$LoginHint
    )
    $pkce  = New-PimEpPkcePair
    $state = [guid]::NewGuid().ToString('N')
    $scope = Get-PimEpScopeString -Scopes $Scopes
    $tcp = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
    $tcp.Start(); $tcps = @($tcp); try { if ([System.Net.Sockets.Socket]::OSSupportsIPv6) { $tcp6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, ([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port); $tcp6.Start(); $tcps += $tcp6 } } catch { }   # a customer 2026-10-21: "localhost" may be [::1] -- BOTH loopbacks, same port
    $redirect = "http://localhost:$(([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port)/"
    $authUrl  = New-PimEpAuthorizeUrl -Tenant $Tenant -ClientId $ClientId -RedirectUri $redirect -Scope $scope -State $state -CodeChallenge $pkce.Challenge -LoginHint $LoginHint
    $query = $null
    try {
        $edge = if ($UseEdge) { Get-PimEpEdgePath } else { $null }
        # -WhatIf:$false -- the sign-in is a READ the preview needs: an inherited -WhatIf would stop Start-Process from
        # opening the browser and the run would wait 5 minutes for an answer that never comes.
        if ($edge) {
            Write-Host "Opening Microsoft Edge for sign-in (answer comes back to $redirect)..." -ForegroundColor Yellow
            Start-Process -FilePath $edge -ArgumentList @('--new-window', $authUrl) -WhatIf:$false
        } else {
            if ($UseEdge) { Write-Host 'Microsoft Edge not found -- using the default browser.' -ForegroundColor DarkYellow }
            Write-Host "Opening the default browser for sign-in (answer comes back to $redirect)..." -ForegroundColor Yellow
            Start-Process $authUrl -WhatIf:$false
        }
        Write-Host "If no browser opened, open this address yourself:`n  $authUrl" -ForegroundColor DarkGray
        # SIGNIN-PAGE (owner 2026-10-31, Invardia's Wait-AuthCode fix): only the answer (code / error) ends the wait, every
        # request gets a page, and the page keeps answering 10 s after it (PIM-LoopbackAnswer.ps1; tools/setup/_PimLoopbackAnswer.ps1 is its identical copy for the tools).
        if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: _PimLoopbackAnswer.ps1 =====
# PIM-LoopbackAnswer.ps1 -- the ONE wait for a browser sign-in's answer on the localhost loopback (auth code + PKCE).
# Used by every PIM browser sign-in: the REST library's own (signed-in setup scripts), the mail setup (Initialize-PimMailSender,
# Set-PimSmtpRelayPassword, Set-PimSqlTier), the engine-permissions grant and the Activator deploy scripts. The tools load the
# identical copy in tools\setup (they may not load engine files). Build-PimSupportScripts inlines it into each published script.
#
# Owner 2026-10-30/31 ("people are reporting this error" -- "This site can't be reached"; "yes fix the sign-in page in all
# scripts"), the same fix as Invardia's Wait-AuthCode: the old loops took the FIRST request -- often the browser's preload
# of the address or its icon request -- and a request that never sent a line held the loop, and once the answer came the
# listener stopped at once, so the browser's real load or a reload got "This site can't be reached". Now:
#   1. only a request whose query carries code= or error= is the answer; the loop goes on until one comes;
#   2. EVERY request gets a page (waiting / signed in / failed), never a closed connection;
#   3. after the answer the listener keeps answering for -GraceSeconds (10), so a second load shows "Signed in" too;
#   4. it throws only when no answer came within -Seconds.
# A connection that sends nothing (a speculative preconnect) is dropped after -ReadTimeoutMs and never blocks the loop.

function Test-PimLoopbackAnswerQuery {
    # PURE. Is this request line the sign-in's answer? Returns the query string ('' when not).
    param([AllowEmptyString()][AllowNull()][string]$RequestLine)
    $m = [regex]::Match("$RequestLine", '^GET /[^?\s]*\?(?<q>\S+) HTTP')
    if (-not $m.Success) { return '' }
    $q = $m.Groups['q'].Value
    if ($q -match '(^|&)(code|error)=') { return $q }
    return ''
}

function Get-PimLoopbackPage {
    # PURE. The page for one request: before the answer 'waiting', after it 'done' (or 'failed' when the answer is an error).
    param([ValidateSet('waiting', 'done', 'failed')][string]$Kind, [string]$ReturnTo = 'PowerShell', [string]$ErrorText = '')
    $body = switch ($Kind) {
        'waiting' { '<h3>Waiting for the sign-in...</h3>Finish the sign-in in the other tab.' }
        'done'    { "<h3>Sign-in complete.</h3>You can close this tab and return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
        'failed'  { "<h3>Sign-in failed</h3>$([System.Net.WebUtility]::HtmlEncode($ErrorText))<br>Return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
    }
    "<html><head><meta charset=`"utf-8`"></head><body style=`"font-family:sans-serif`">$body</body></html>"
}

function Wait-PimLoopbackAnswer {
    <#
      Waits on the loopback listener(s) (TcpListener, started by the caller; both loopbacks may share one port) for the
      sign-in's answer and returns its raw query string. Throws only when no answer came within -Seconds. The caller still
      checks state / error / code and stops the listeners (this function does not stop them).
    #>
    param([Parameter(Mandatory)][object[]]$Listeners, [int]$Seconds = 300, [int]$GraceSeconds = 10, [int]$ReadTimeoutMs = 2000,
          [string]$ReturnTo = 'PowerShell', [string]$TimeoutMessage = '')
    $deadline = [DateTime]::UtcNow.AddSeconds($Seconds); $graceEnd = $null
    $answer = $null; $kind = 'waiting'; $errText = ''
    while ($true) {
        $now = [DateTime]::UtcNow
        if ($answer) { if ($now -ge $graceEnd) { break } } elseif ($now -ge $deadline) { break }
        $ready = @($Listeners | Where-Object { $_.Pending() })[0]
        if (-not $ready) { Start-Sleep -Milliseconds 100; continue }
        $client = $null
        try {
            $client = $ready.AcceptTcpClient()
            $client.ReceiveTimeout = $ReadTimeoutMs
            $stream = $client.GetStream()
            $reader = New-Object System.IO.StreamReader($stream)
            $line = $null
            try { $line = $reader.ReadLine() } catch { $line = $null }   # a connection that sends nothing: dropped, never waited on
            if ($null -eq $line) { continue }
            if (-not $answer) {
                $q = Test-PimLoopbackAnswerQuery -RequestLine $line
                if ($q) {
                    $answer = $q; $graceEnd = [DateTime]::UtcNow.AddSeconds($GraceSeconds)
                    if ($q -match '(^|&)error=') {
                        $kind = 'failed'
                        $d = [regex]::Match($q, '(^|&)error_description=(?<d>[^&]*)')
                        $errText = if ($d.Success) { [uri]::UnescapeDataString(($d.Groups['d'].Value -replace '\+', ' ')) } else { '' }
                    } else { $kind = 'done' }
                }
            }
            $html = Get-PimLoopbackPage -Kind $kind -ReturnTo $ReturnTo -ErrorText $errText
            $bytes = [Text.Encoding]::UTF8.GetBytes($html)
            $head = [Text.Encoding]::ASCII.GetBytes("HTTP/1.1 200 OK`r`nContent-Type: text/html; charset=utf-8`r`nContent-Length: $($bytes.Length)`r`nConnection: close`r`n`r`n")
            $stream.Write($head, 0, $head.Length); $stream.Write($bytes, 0, $bytes.Length); $stream.Flush()
        } catch { }   # a browser that closed the connection itself: nothing to answer
        finally { if ($client) { try { $client.Close() } catch { } } }
    }
    if (-not $answer) {
        throw $(if ("$TimeoutMessage".Trim()) { $TimeoutMessage } else { "Timed out ($([int]($Seconds / 60)) minutes) waiting for the browser to finish the sign-in." })
    }
    return $answer
}

# ===== END inlined helper: _PimLoopbackAnswer.ps1 =====
        }
        $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 minutes) waiting for the browser to finish the sign-in.'
    } finally { foreach ($tcpL in $tcps) { try { $tcpL.Stop() } catch { } } }
    $kv = @{}
    foreach ($pair in ($query -split '&')) {
        $k, $v = $pair -split '=', 2
        $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+', ' ')) } else { '' }
    }
    if ($kv['error'])            { throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])" }
    if ($kv['state'] -ne $state) { throw 'The browser answer did not come from this sign-in attempt. Close ALL browser windows and run the script again.' }
    if (-not $kv['code'])        { throw 'The browser answer carried no authorization code.' }
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id     = $ClientId
        grant_type    = 'authorization_code'
        code          = $kv['code']
        redirect_uri  = $redirect
        code_verifier = $pkce.Verifier
        scope         = $scope
    }
}

# ---- tokens + the REST seam -------------------------------------------------------------------------------------------
# $script:PimEpTokens = @{ graph = '<token>'; arm = '<token>' } -- set by the sign-in (or -GraphAccessToken / -ArmAccessToken).
function Set-PimEpToken {
    param([Parameter(Mandatory)][ValidateSet('graph', 'arm')][string]$Api, [Parameter(Mandatory)][string]$AccessToken)
    if (-not $script:PimEpTokens) { $script:PimEpTokens = @{} }
    $script:PimEpTokens[$Api] = $AccessToken
}

function Resolve-PimEpUri {
    param([ValidateSet('graph', 'arm')][string]$Api = 'graph', [Parameter(Mandatory)][string]$Path)
    if ($Path -match '^https?://') { return $Path }
    if ($Api -eq 'arm') { return 'https://management.azure.com/' + $Path.TrimStart('/') }
    $rel = $Path.TrimStart('/')
    if ($rel -match '^(v1\.0|beta)/') { return "https://graph.microsoft.com/$rel" }
    "https://graph.microsoft.com/v1.0/$rel"
}

# HTTP status of a failed Invoke-RestMethod (5.1 WebException / 7 HttpResponseException), message as fallback. 0 = unknown.
function Get-PimEpHttpStatus {
    param($ErrorRecord)
    $ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
    try { if ($ex.Response -and $ex.Response.StatusCode) { return [int]$ex.Response.StatusCode } } catch { }
    $m = "$($ex.Message)"
    if ($m -match '\((\d{3})\)') { return [int]$Matches[1] }
    if ($m -match 'status code[^0-9]{0,40}(\d{3})') { return [int]$Matches[1] }
    0
}

# "<code>: <message>" from the JSON error body (Graph and ARM use the same { error: { code, message } } shape).
function Get-PimEpErrorText {
    param($ErrorRecord)
    $raw = $null
    if ($ErrorRecord -is [System.Management.Automation.ErrorRecord] -and $ErrorRecord.ErrorDetails -and $ErrorRecord.ErrorDetails.Message) { $raw = $ErrorRecord.ErrorDetails.Message }
    if (-not $raw) {
        try {
            $resp = $ErrorRecord.Exception.Response
            if ($resp -and ($resp | Get-Member -Name GetResponseStream -MemberType Method)) { $raw = (New-Object System.IO.StreamReader($resp.GetResponseStream())).ReadToEnd() }
        } catch { }
    }
    if (-not $raw) { return "$($ErrorRecord.Exception.Message)" }
    try { $j = $raw | ConvertFrom-Json; if ($j.error) { return "$($j.error.code): $($j.error.message)" } } catch { }
    "$raw"
}

# One call to Graph or ARM. JSON bodies go as UTF-8. Collections come back as their `value` items (-All follows
# @odata.nextLink / nextLink). 429/503/504 are retried. A failure throws "HTTP <n> <code>: <message>".
function Invoke-PimEpRest {
    param(
        [ValidateSet('graph', 'arm')][string]$Api = 'graph',
        [string]$Method = 'GET',
        [Parameter(Mandatory)][string]$Path,
        [object]$Body,
        [switch]$All,
        [int]$MaxRetries = 4
    )
    $tok = $null; if ($script:PimEpTokens) { $tok = $script:PimEpTokens[$Api] }
    if (-not $tok) { throw "Not signed in to $(if ($Api -eq 'arm') { 'Azure' } else { 'Microsoft Graph' })." }
    $uri = Resolve-PimEpUri -Api $Api -Path $Path
    $bytes = $null
    if ($null -ne $Body) { $bytes = [Text.Encoding]::UTF8.GetBytes($(if ($Body -is [string]) { $Body } else { ConvertTo-Json -InputObject $Body -Depth 10 -Compress })) }
    $send = {
        param([string]$M, [string]$U, [byte[]]$B)
        for ($try = 0; ; $try++) {
            $p = @{ Method = $M; Uri = $U; Headers = @{ Authorization = "Bearer $tok" }; ErrorAction = 'Stop' }
            if ($null -ne $B) { $p.Body = $B; $p.ContentType = 'application/json; charset=utf-8' }
            try { return Invoke-RestMethod @p }
            catch {
                $code = Get-PimEpHttpStatus $_
                if (($code -in @(429, 503, 504)) -and ($try -lt $MaxRetries)) { Start-Sleep -Seconds ([int][Math]::Min(30, [Math]::Pow(2, $try + 1))); continue }
                $ct = if ($code) { "HTTP $code " } else { '' }
                throw "$ct$(Get-PimEpErrorText $_)"
            }
        }
    }
    $resp = & $send $Method $uri $bytes
    $vp = $null; if ($null -ne $resp -and $resp.PSObject) { $vp = $resp.PSObject.Properties['value'] }
    if (-not ($vp -and ($null -eq $vp.Value -or $vp.Value -is [array]))) { return $resp }
    $items = New-Object System.Collections.Generic.List[object]
    $page = $resp
    while ($true) {
        foreach ($i in @($page.value)) { if ($null -ne $i) { $items.Add($i) } }
        if (-not $All) { break }
        $next = $null
        foreach ($n in '@odata.nextLink', 'nextLink') { if ($page.PSObject.Properties[$n] -and $page.$n) { $next = "$($page.$n)"; break } }
        if (-not $next) { break }
        $page = & $send 'GET' $next $null
    }
    $items.ToArray()
}

# The status number in an error text thrown by Invoke-PimEpRest (0 = none).
function Get-PimEpErrorStatus {
    param([AllowEmptyString()][string]$Text)
    if ("$Text" -match '^HTTP (\d{3})') { return [int]$Matches[1] }
    0
}

# ---- the grant ----------------------------------------------------------------------------------------------------------
function New-PimEpResult {
    param([string]$Kind, [string]$What, [string]$Where, [string]$Status, [string]$Detail = '')
    [pscustomobject]@{ kind = $Kind; what = $What; where = $Where; status = $Status; detail = $Detail }
}

# Application permissions (Graph and others) for the engine identity. Needs the Graph token. Idempotent: what is
# already held is reported and left alone; every grant is read back.
function Invoke-PimEpAppRoleGrant {
    param([Parameter(Mandatory)][string]$EngineObjectId, [object[]]$Specs, [switch]$PlanOnly)
    $results = New-Object System.Collections.Generic.List[object]
    if (-not @($Specs).Count) { return $results.ToArray() }
    $sps = @{}
    foreach ($appId in @($Specs | ForEach-Object { $_.resourceAppId } | Select-Object -Unique)) {
        $r = @(Invoke-PimEpRest -Api graph -Path ("/servicePrincipals?`$filter=appId eq '{0}'&`$select=id,appId,displayName,appRoles" -f $appId))
        $sps[$appId] = $(if ($r.Count) { $r[0] } else { $null })
    }
    $existing = @(Invoke-PimEpRest -Api graph -Path "/servicePrincipals/$EngineObjectId/appRoleAssignments" -All)
    $plan = @(Get-PimEpAppRolePlan -Wanted $Specs -ResourceSps $sps -Existing $existing)
    $toCheck = New-Object System.Collections.Generic.List[object]
    foreach ($p in $plan) {
        $where = if ($p.resourceName) { $p.resourceName } else { $p.resourceAppId }
        switch ($p.action) {
            'present'      { $results.Add((New-PimEpResult 'app permission' $p.value $where 'already there')) }
            'no-resource'  { $results.Add((New-PimEpResult 'app permission' $p.value $where 'refused' "the API $($p.resourceAppId) has no service principal in this tenant")) }
            'unknown-role' { $results.Add((New-PimEpResult 'app permission' $p.value $where 'refused' "$where has no application permission named '$($p.value)'")) }
            'grant' {
                if ($PlanOnly) { $results.Add((New-PimEpResult 'app permission' $p.value $where 'would grant')); continue }
                $req = New-PimEpAppRoleAssignmentRequest -PrincipalId $EngineObjectId -ResourceId $p.resourceId -AppRoleId $p.appRoleId
                try {
                    [void](Invoke-PimEpRest -Api graph -Method $req.Method -Path $req.Path -Body $req.Body)
                    $toCheck.Add($p)
                } catch {
                    $msg = "$_"; $st = Get-PimEpErrorStatus $msg
                    if ($st -eq 400 -and $msg -match '(?i)already exists') { $results.Add((New-PimEpResult 'app permission' $p.value $where 'already there')) }
                    elseif ($st -eq 403 -or $st -eq 401) { $results.Add((New-PimEpResult 'app permission' $p.value $where 'refused' "$msg -- sign in as a Global Administrator or Privileged Role Administrator")) }
                    else { $results.Add((New-PimEpResult 'app permission' $p.value $where 'refused' $msg)) }
                }
            }
        }
    }
    if ($toCheck.Count) {
        # read back: every grant must now be on the engine identity
        $after = @(Invoke-PimEpRest -Api graph -Path "/servicePrincipals/$EngineObjectId/appRoleAssignments" -All)
        $held = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
        foreach ($a in $after) { if ($a) { [void]$held.Add("$($a.resourceId)|$($a.appRoleId)") } }
        foreach ($p in $toCheck) {
            $where = if ($p.resourceName) { $p.resourceName } else { $p.resourceAppId }
            if ($held.Contains("$($p.resourceId)|$($p.appRoleId)")) { $results.Add((New-PimEpResult 'app permission' $p.value $where 'granted')) }
            else { $results.Add((New-PimEpResult 'app permission' $p.value $where 'granted' 'accepted, not visible on the read-back yet -- check again in a minute')) }
        }
    }
    $results.ToArray()
}

# Azure role assignments for the engine identity. Needs the ARM token. Idempotent: an assignment at (or above) the
# scope is reported and left alone; a new one gets a new GUID and is read back.
function Invoke-PimEpAzureRoleGrant {
    param([Parameter(Mandatory)][string]$EngineObjectId, [object[]]$Specs, [switch]$PlanOnly)
    $results = New-Object System.Collections.Generic.List[object]
    $api = Get-PimEpArmApiVersion
    foreach ($s in @($Specs)) {
        if (-not $s) { continue }
        $prefix = if ($s.scope -eq '/') { '' } else { $s.scope }
        $guid = $s.roleDefinitionGuid
        try {
            if (-not $guid) {
                $f = [uri]::EscapeDataString("roleName eq '$($s.role.Replace("'", "''"))'")
                $defs = @(Invoke-PimEpRest -Api arm -Path "$prefix/providers/Microsoft.Authorization/roleDefinitions?`$filter=$f&api-version=$api")
                if (-not $defs.Count) { $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'refused' "no Azure role named '$($s.role)' at this scope")); continue }
                $guid = "$($defs[0].name)".ToLowerInvariant()
            }
            $cur = @(Invoke-PimEpRest -Api arm -Path "$prefix/providers/Microsoft.Authorization/roleAssignments?`$filter=assignedTo('$EngineObjectId')&api-version=$api" -All)
            $hit = Find-PimEpArmAssignment -Assignments $cur -Scope $s.scope -RoleDefinitionGuid $guid
            if ($hit) {
                $d = if ($hit.how -eq 'inherited') { "inherited from $($hit.scope)" } else { '' }
                $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'already there' $d)); continue
            }
            if ($PlanOnly) { $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'would grant')); continue }
            $req = New-PimEpArmRoleAssignmentRequest -Scope $s.scope -RoleDefinitionGuid $guid -PrincipalId $EngineObjectId
            try { [void](Invoke-PimEpRest -Api arm -Method $req.Method -Path $req.Path -Body $req.Body) }
            catch {
                $msg = "$_"; $st = Get-PimEpErrorStatus $msg
                if ($st -eq 409 -and $msg -match '(?i)RoleAssignmentExists') { $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'already there')); continue }
                if ($st -eq 403 -or $st -eq 401) {
                    $hint = 'you need Owner or User Access Administrator at this scope'
                    if ($s.scope -match '(?i)managementGroups') { $hint += "; at the tenant root a Global Administrator first turns on 'Access management for Azure resources' (Microsoft Entra ID > Properties), then runs this script again" }
                    $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'refused' "$msg -- $hint")); continue
                }
                $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'refused' $msg)); continue
            }
            $back = $null
            try { $back = Invoke-PimEpRest -Api arm -Path ($req.Path) } catch { $back = $null }
            if ($back -and "$($back.properties.principalId)" -eq $EngineObjectId) { $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'granted')) }
            else { $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'granted' 'accepted, not readable yet -- check again in a minute')) }
        } catch {
            $results.Add((New-PimEpResult 'Azure role' $s.role $s.scope 'refused' "$_"))
        }
    }
    $results.ToArray()
}

# The result table for the console (pure: returns the lines).
function Format-PimEpResults {
    param([object[]]$Results)
    $lines = New-Object System.Collections.Generic.List[string]
    foreach ($r in @($Results)) {
        if (-not $r) { continue }
        $l = '  {0,-14} {1,-15} {2} ({3})' -f $r.status, $r.kind, $r.what, $r.where
        if ($r.detail) { $l += " -- $($r.detail)" }
        $lines.Add($l)
    }
    $lines.ToArray()
}

# ===== END inlined helper: _PimEnginePermissions.ps1 =====
# ===== BEGIN inlined helper: _PimScriptDoc.ps1 =====
<#
.SYNOPSIS
    Framework 12.7 SCRIPT-DOC-1 + 12.10 item 11 -- the ONE place that knows where a PIM script's documentation page,
    download and checksum list live, the command form every surface shows (line 1 download, line 2+ run -- owner
    2026-10-11), and the run
    frame every script a person runs uses (the first line "<Script> version <x.y.z> - documentation: <page>",
    REQUIREMENTS 100.52, and a local transcript).

.DESCRIPTION
    PURE except Start-PimScriptRun / Stop-PimScriptRun (they print and start / stop a transcript in the temp folder).
    Loaded by every in-scope script (tools\setup + tools\pim-activator), by Build-PimSupportScripts.ps1 (it inlines this
    file into each standalone), by the Manager (Open-PimManager.ps1 hands the constants to the page) and by the engine
    libraries that build fix commands (PIM-PermissionHealth, PIM-MailTransport, PIM-WorkloadPrereqs).
    Change a URL HERE and only here: tests\Test-PimScriptDocs.ps1 fails on any script whose .LINK, page constant or
    manifest docUrl disagrees with it.

    The in-scope list ($script:PimScriptDocScripts) is the set of scripts a person runs that 12.7 covers: each has a
    manifest tools\setup\script-docs\<Script>.doc.json, a .LINK to its page, the Documentation line, -WhatIf, and a
    -WhatIf run case under tests\script-docs\.
#>

# --- the constants (Invardia confirmed 2026-10-09: page = <base><Script>/ with a trailing slash; index = <base>) -------
$script:PimScriptDocBaseUrl     = 'https://invardia.com/docs/pim/scripts/'
$script:PimSupportScriptBaseUrl = 'https://invardia.com/support/pim/'
# ONE-LINE-INSTALL (owner 2026-11-02): the installer launcher is a file of the public release (a release asset)
$script:PimInstallReleaseDownloadBase = 'https://github.com/KnudsenMorten/PIM4EntraPS/releases/latest/download/'
$script:PimSupportScriptSumsUrl = 'https://invardia.com/support/pim/SHA256SUMS.txt'

# --- the version the banner names (REQUIREMENTS 100.52, owner 2026-10-10: "do you provide the version in all scripts, so i
# can troubleshoot better"). Build-PimSupportScripts.ps1 rewrites the NEXT line in a standalone file to the version it was
# built from (the marker comment is what it looks for); in the repository it stays empty and Get-PimScriptVersion reads
# the solution's VERSION file next to this helper (tools\setup\..\..\VERSION).
$script:PimScriptDocVersion = '3.0.70'   # BUILD-VERSION stamped by Build-PimSupportScripts
$script:PimScriptDocHelperDir = "$PSScriptRoot"

# --- every script 12.7 covers: path relative to tools\ ; Standalone = published as one file by Build-PimSupportScripts --
$script:PimScriptDocScripts = @(
    @{ Path = 'setup/Initialize-PimSqlAdminGroup.ps1';             Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorBackend.ps1';      Standalone = $true }
    @{ Path = 'pim-activator/Publish-PimActivatorRemediation.ps1'; Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorClient.ps1';       Standalone = $true }
    @{ Path = 'setup/Grant-PimEnginePermissions.ps1';              Standalone = $true }
    @{ Path = 'setup/Initialize-PimWorkloadPrereqs.ps1';           Standalone = $true }
    @{ Path = 'setup/Initialize-PimMailSender.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSmtpRelayPassword.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSqlTier.ps1';                          Standalone = $true }
    @{ Path = 'setup/New-PimHubPrepareScript.ps1';                 Standalone = $true }
    @{ Path = 'setup/Install-PimManager.ps1';                      Standalone = $false }
    @{ Path = 'setup/Invoke-PimDeployAll.ps1';                     Standalone = $false }
    @{ Path = 'setup/Invoke-PimMspBuild.ps1';                      Standalone = $false }
    @{ Path = 'setup/Copy-PimSettings.ps1';                        Standalone = $false }
    @{ Path = 'setup/Export-PimSettings.ps1';                      Standalone = $false }   # 77.13 / 72.4 settings as code
    @{ Path = 'setup/Import-PimSettings.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerAccess.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimBreakGlassAccounts.ps1';               Standalone = $false }
    @{ Path = 'setup/Set-PimEmergencyPassphrase.ps1';              Standalone = $false }
    @{ Path = 'setup/Find-PimStrayTestObjects.ps1';                Standalone = $false }
    @{ Path = 'setup/Move-PimIdentities.ps1';                      Standalone = $false }   # NAM-03 identity mover
    @{ Path = 'setup/Rename-PimJobs.ps1';                          Standalone = $false }   # JOB-RENAME 3.0.68 job rename (create, prove, switch, disable)
    @{ Path = 'setup/Set-PimLicense.ps1';                          Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorHybrid.ps1';       Standalone = $false }
    @{ Path = 'setup/Update-PimCommunity.ps1';                     Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Confirm-PimInstall.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerCustomHost.ps1';                Standalone = $false }
    @{ Path = 'setup/Deploy-PimRfaBroker.ps1';                     Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvInternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvExternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Remove-PimContainerStack.ps1';                Standalone = $false }
    @{ Path = 'setup/New-PimHostingPrerequisites.ps1';             Standalone = $false }
    @{ Path = 'setup/Convert-PimToPrivate.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimSqlPublicAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportSqlAccess.ps1';               Standalone = $true }
    @{ Path = 'setup/Invoke-PimSupportSqlAccessJob.ps1';           Standalone = $true }
    @{ Path = 'setup/Set-PimSigninFrontSqlState.ps1';              Standalone = $true }
    # HYBRID-DEPLOY-STANDALONE: one published file that carries the worker's other scripts (BUILD-CARRY) and runs them from a temp folder
    @{ Path = 'pim-hybrid-worker/Deploy-PimHybridWorker.ps1';      Standalone = $true }
    @{ Path = 'pim-hybrid-worker/New-PimHybridWorkerInfra.ps1';    Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerPeering.ps1';  Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerEgress.ps1';   Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Grant-PimHybridWorkerAccess.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Invoke-PimHybridWorkerRunCommand.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Remove-PimHybridWorker.ps1';      Standalone = $false }
    # self-contained on the machine they run on (a domain controller; the worker itself): published as one file each
    @{ Path = 'pim-hybrid-worker/Initialize-PimHybridWorkerAd.ps1'; Standalone = $true }
    @{ Path = 'pim-hybrid-worker/Install-PimHybridWorker.ps1';     Standalone = $true }
    # INSTALL-SAMPLES (owner 2026-10-29): the one-file launcher of the installation (downloads the release, runs its installer)
    @{ Path = 'setup/Start-PimManagerInstall.ps1';                 Standalone = $true }
    # V1-IMPORT-PUBLISHED (Invardia per 0.1 B, 2026-11-03): import a PIM version 1 data folder (check + preview by default)
    @{ Path = 'setup/Import-PimV1Data.ps1';                        Standalone = $true }
)

function Get-PimScriptDocName {
    # PURE. 'Grant-PimEnginePermissions.ps1' / '.\x\Grant-PimEnginePermissions' -> 'Grant-PimEnginePermissions'.
    param([Parameter(Mandatory)][string]$Script)
    $leaf = "$Script".Trim() -replace '^.*[\\/]', ''
    return ($leaf -replace '(?i)\.ps1$', '')
}

function Get-PimScriptDocUrl {
    # PURE. The script's documentation page at Invardia: <base><Script>/ (no .ps1, trailing slash).
    param([Parameter(Mandatory)][string]$Script)
    return ($script:PimScriptDocBaseUrl + (Get-PimScriptDocName -Script $Script) + '/')
}

function Get-PimSupportScriptUrl {
    # PURE. The published standalone copy: <support base><Script>.ps1 -- except the installer launcher, which is a file of
    # the public GitHub release itself (ONE-LINE-INSTALL, owner 2026-11-02: line 1 downloads it from the release, never
    # from invardia.com), under a stable name so .../releases/latest/download/<name> always answers.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ($name -eq 'Start-PimManagerInstall') { return "$script:PimInstallReleaseDownloadBase$name.ps1" }
    return ($script:PimSupportScriptBaseUrl + $name + '.ps1')
}

function Get-PimSupportScriptCommand {
    <#
      PURE. The lines every surface shows for a published script (owner 2026-10-11, framework 12.10 item 11):
        Invoke-WebRequest <url> -OutFile <Script>.ps1        line 1: download the file from Invardia
        <-Run lines>                                          line 2 (and more if a flow needs them): the cmdlet(s)
      Never a checksum / comment line in the shown block, never pipe-to-execute: the documentation page is the link
      shown NEXT to the command; SHA256SUMS.txt stays published for whoever verifies.
      The run line is LAST on purpose: callers that append parameters to the returned text extend the run line.
      -Run: the command line(s) that run the saved file, e.g. ".\Grant-PimEnginePermissions.ps1 -TenantId '...'";
      none = ".\<Script>.ps1". Returns string[] (join with a newline to show / send).
    #>
    param([Parameter(Mandatory)][string]$Script, [string[]]$Run = @())
    $name = Get-PimScriptDocName -Script $Script
    $file = "$name.ps1"
    $lines = New-Object System.Collections.Generic.List[string]
    # Owner 2026-10-11: TWO lines only -- line 1 downloads the file, line 2 runs it (the doc page is linked next to the
    # command on every surface; SHA256SUMS.txt stays published for whoever wants to verify).
    $lines.Add("Invoke-WebRequest $(Get-PimSupportScriptUrl -Script $name) -OutFile $file")
    $runs = @(@($Run) | Where-Object { "$_".Trim() })
    if (-not $runs.Count) { $runs = @(".\$file") }
    foreach ($r in $runs) { $lines.Add("$r") }
    return $lines.ToArray()
}

function Get-PimSupportScriptDocLine {
    # PURE. REQUIREMENTS 100.77 (owner 2026-10-11, "Yes, outside block"): the ONE plain line that goes UNDER a command block
    # in PLAIN TEXT (an install event / install mail, "Send to customer", a console fix, a report), where no link can sit
    # next to the block the way the Manager page shows it: "What does this script do: <the script's doc page>".
    param([Parameter(Mandatory)][string]$Script)
    return ('What does this script do: ' + (Get-PimScriptDocUrl -Script $Script))
}

function Add-PimSupportScriptDocLines {
    <#
      PURE. REQUIREMENTS 100.77. Plain text that carries one or more published-script command blocks (the lines
      Get-PimSupportScriptCommand returns: "Invoke-WebRequest <support base><Script>.ps1 -OutFile <Script>.ps1", then the
      ".\<Script>.ps1 ..." run line(s)) -> the same text with Get-PimSupportScriptDocLine inserted directly UNDER each
      block's last run line, at the block's indentation. The block itself is never changed (it stays exactly its download
      line + run line(s), framework 12.10 item 11): the doc line is a separate line outside it. Idempotent (a block already
      followed by its doc line is left alone); text without a block comes back unchanged; the newline style is kept.
      Use it ONLY where text leaves the page as plain text -- the Manager page shows the link next to the block instead.
    #>
    param([AllowNull()][AllowEmptyString()][string]$Text)
    $t = "$Text"
    if (-not $t) { return $t }
    $nl = if ($t.Contains("`r`n")) { "`r`n" } else { "`n" }
    $lines = @($t -split "\r?\n")
    $base = [regex]::Escape($script:PimSupportScriptBaseUrl)
    $out = New-Object System.Collections.Generic.List[string]
    $i = 0
    while ($i -lt $lines.Count) {
        $l = $lines[$i]; $out.Add($l); $i++
        $m = [regex]::Match($l, "^(?<ind>\s*)Invoke-WebRequest\s+$base(?<n>[A-Za-z0-9-]+)\.ps1\s+-OutFile\s+\k<n>\.ps1\s*$")
        if (-not $m.Success) { continue }
        $n = $m.Groups['n'].Value
        $runRx = '^\s*\.\\' + [regex]::Escape($n) + '\.ps1(\s|$)'
        while ($i -lt $lines.Count -and $lines[$i] -match $runRx) { $out.Add($lines[$i]); $i++ }
        $doc = Get-PimSupportScriptDocLine -Script $n
        if ($i -lt $lines.Count -and $lines[$i].Trim() -eq $doc) { continue }
        $out.Add($m.Groups['ind'].Value + $doc)
    }
    return ($out.ToArray() -join $nl)
}

function Get-PimScriptVersion {
    # The PIM version this script is: the build stamp in a standalone file, else the solution's VERSION file (resolved
    # from this helper's folder), else 'unknown' (a copied helper with nothing around it -- never a failure).
    param([string]$Stamp = "$($script:PimScriptDocVersion)", [string]$HelperDir = "$($script:PimScriptDocHelperDir)")
    if ("$Stamp".Trim()) { return "$Stamp".Trim() }
    if ("$HelperDir".Trim()) {
        try {
            $vf = Join-Path (Split-Path (Split-Path $HelperDir -Parent) -Parent) 'VERSION'
            if (Test-Path -LiteralPath $vf -PathType Leaf) {
                $v = "$([IO.File]::ReadAllText($vf))".Trim()
                if ($v) { return $v }
            }
        } catch { }
    }
    return 'unknown'
}

function Get-PimScriptBannerText {
    # PURE. The banner line: "<Script> version <x.y.z> - documentation: <doc page>".
    param([Parameter(Mandatory)][string]$Script, [Parameter(Mandatory)][string]$Version)
    $name = Get-PimScriptDocName -Script $Script
    return ('{0} version {1} - documentation: {2}' -f $name, $Version, (Get-PimScriptDocUrl -Script $name))
}

function Write-PimScriptBanner {
    <#
      REQUIREMENTS 100.52: the FIRST line every script a person runs prints -- its own name, version and documentation
      page -- so a transcript a customer sends shows exactly what ran. Called by Start-PimScriptRun (every in-scope script
      calls that first thing after loading its helpers), so it is written once, here.
      Write-Host = the host / Information stream: Start-Transcript records it, the pipeline (JSON, -PassThru) never sees
      it, -WhatIf does not change it.
      Printed by the OUTERMOST script only: a script called by another in the same process (the owner flag is set until
      the outer one's Stop-PimScriptRun) or in a child process it started (PIM_SCRIPT_BANNER_PID names a live parent)
      prints nothing. Returns $true when it printed.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)") { return $false }
    $parentPid = 0
    if ([int]::TryParse("$env:PIM_SCRIPT_BANNER_PID", [ref]$parentPid) -and $parentPid -gt 0 -and $parentPid -ne $PID) {
        if (Get-Process -Id $parentPid -ErrorAction SilentlyContinue) { return $false }
    }
    $global:PimScriptBannerOwner = $name
    $env:PIM_SCRIPT_BANNER_PID = "$PID"
    Write-Host (Get-PimScriptBannerText -Script $name -Version (Get-PimScriptVersion))
    return $true
}

function Start-PimScriptRun {
    <#
      12.7 + 12.10 item 11: call it right after the param block / helper loading, BEFORE anything else prints.
      Starts a transcript in <temp>\pim-manager-logs\<Script>-<utc>.log (nothing else on disk; the temp folder is the
      one place -WhatIf may write) and prints, as the first line, the banner (Write-PimScriptBanner, REQUIREMENTS 100.52:
      "<Script> version <x.y.z> - documentation: <doc page>"; the outermost script only), then "Log: <path>".
      Nested runs (one in-scope script calling another in the same process) keep the outer transcript.
      Returns the log path ('' when the transcript could not start -- the run goes on, with a warning).
      Scripts print no secret values (SECRET-IN-OUTPUT audit), so the transcript holds none either.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    $path = ''
    if ("$($global:PimScriptRunLog)") {
        $path = "$($global:PimScriptRunLog)"
    } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') {
        try {
            $dir = Join-Path ([IO.Path]::GetTempPath()) 'pim-manager-logs'
            if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force -WhatIf:$false -Confirm:$false | Out-Null }
            $path = Join-Path $dir ('{0}-{1}.log' -f $name, [DateTime]::UtcNow.ToString('yyyyMMdd-HHmmss'))
            Start-Transcript -LiteralPath $path -Append -WhatIf:$false -Confirm:$false | Out-Null
            $global:PimScriptRunLog = $path
            $global:PimScriptRunOwner = $name
        } catch { $path = '' }
    }
    $null = Write-PimScriptBanner -Script $name   # 100.52: "<Script> version <x.y.z> - documentation: <page>" (outermost only)
    if ($path) { Write-Host "Log: $path" } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') { Write-Warning 'No transcript could be started for this run.' }
    return $path
}

function Stop-PimScriptRun {
    # Call it in the script's finally block: prints "Log written: <path>" and stops the transcript this script started.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)" -eq $name) {
        # 100.52: the outermost script is done -- the next script run in this session prints its banner again
        $global:PimScriptBannerOwner = $null
        if ("$env:PIM_SCRIPT_BANNER_PID" -eq "$PID") { $env:PIM_SCRIPT_BANNER_PID = $null }
    }
    if (-not "$($global:PimScriptRunLog)" -or "$($global:PimScriptRunOwner)" -ne $name) { return }
    $path = "$($global:PimScriptRunLog)"
    Write-Host "Log written: $path"
    try { Stop-Transcript | Out-Null } catch { }
    $global:PimScriptRunLog = $null
    $global:PimScriptRunOwner = $null
}

# ===== END inlined helper: _PimScriptDoc.ps1 =====
$null = Start-PimScriptRun -Script 'Grant-PimEnginePermissions'
try {
# -WhatIf = -PlanOnly (sign in, read, report "would grant", write nothing) plus a "What if:" line per grant.
$previewOnly = [bool]$PlanOnly -or [bool]$WhatIfPreference

Write-Host "Grant-PimEnginePermissions -- PIM Manager $(Get-PimEpSolutionVersion)" -ForegroundColor Cyan
Write-Host "PowerShell : $($PSVersionTable.PSVersion) ($($PSVersionTable.PSEdition))" -ForegroundColor Cyan

if (-not (Test-PimEpGuid $EngineObjectId)) { throw "-EngineObjectId must be the engine identity's object id (a GUID): '$EngineObjectId'." }
if ($TenantId -and -not (Test-PimEpGuid $TenantId)) { throw "-TenantId must be the tenant id (a GUID): '$TenantId'." }
$EngineObjectId = $EngineObjectId.ToLowerInvariant()

$appSpecs = New-Object System.Collections.Generic.List[object]
foreach ($g in @(ConvertTo-PimEpList $GraphPermissions)) { $appSpecs.Add((ConvertTo-PimEpAppRoleSpec -Spec $g)) }
foreach ($a in @(ConvertTo-PimEpList $AppRoles)) {
    if ($a -notmatch '@') { throw "-AppRoles entries are '<permission>@<API application id>': '$a' (Microsoft Graph permissions go in -GraphPermissions)." }
    $appSpecs.Add((ConvertTo-PimEpAppRoleSpec -Spec $a))
}
$azSpecs = New-Object System.Collections.Generic.List[object]
foreach ($z in @(ConvertTo-PimEpList $AzureRoleAssignments)) { $azSpecs.Add((ConvertTo-PimEpAzureRoleSpec -Spec $z)) }
if (-not $appSpecs.Count -and -not $azSpecs.Count) { throw 'Nothing to grant: pass -GraphPermissions, -AppRoles and/or -AzureRoleAssignments.' }

$tenant = if ($TenantId) { $TenantId } else { 'organizations' }
$assertTenant = {
    param([string]$Token, [string]$What)
    $c = ConvertFrom-PimEpJwtClaims $Token
    if ($TenantId -and $c -and $c.PSObject.Properties['tid'] -and "$($c.tid)" -ne $TenantId) {
        throw "The $What sign-in landed in tenant $($c.tid), not $TenantId. Sign in with an account of the right tenant."
    }
    $c
}

# ---- Microsoft Graph sign-in + the engine identity ------------------------------------------------------------------
$account = $null
$results = New-Object System.Collections.Generic.List[object]
if ($appSpecs.Count) {
    if ($GraphAccessToken) { $gTok = $GraphAccessToken }
    else {
        Write-Host "Signing in to Microsoft Graph (permissions asked: $((Get-PimEpGraphScopes) -join ', '))..." -ForegroundColor Yellow
        try { $gTok = "$((Get-PimEpInteractiveToken -ClientId (Get-PimEpGraphCliClientId) -Scopes (Get-PimEpGraphScopes) -Tenant $tenant -UseEdge $UseEdge).access_token)" }
        catch { throw ("Sign-in failed: $($_.Exception.Message)`n$(Get-PimEpBrokenAuthHelp)") }
    }
    $claims = & $assertTenant $gTok 'Microsoft Graph'
    if ($claims) { foreach ($n in 'upn', 'preferred_username', 'unique_name') { if ($claims.PSObject.Properties[$n] -and $claims.$n) { $account = "$($claims.$n)"; break } } }
    if ($claims -and -not $TenantId -and $claims.PSObject.Properties['tid']) { $tenant = "$($claims.tid)" }
    Set-PimEpToken -Api graph -AccessToken $gTok
    Write-Host "Signed in$(if ($account) { " as $account" })." -ForegroundColor Green

    try { $eng = Invoke-PimEpRest -Api graph -Path "/servicePrincipals/$($EngineObjectId)?`$select=id,appId,displayName,servicePrincipalType" }
    catch {
        if ((Get-PimEpErrorStatus "$_") -eq 404) { throw "No service principal with object id $EngineObjectId in this tenant. Copy the object id from PIM Manager again." }
        throw "Could not read the engine identity: $_"
    }
    Write-Host "Engine identity: $($eng.displayName) ($($eng.servicePrincipalType), object id $EngineObjectId)" -ForegroundColor Cyan
    foreach ($r in @(Invoke-PimEpAppRoleGrant -EngineObjectId $EngineObjectId -Specs $appSpecs.ToArray() -PlanOnly:$previewOnly)) { $results.Add($r) }
}

# ---- Azure role assignments -------------------------------------------------------------------------------------------
if ($azSpecs.Count) {
    if ($ArmAccessToken) { $aTok = $ArmAccessToken }
    else {
        Write-Host 'Signing in to Azure for the role assignment(s)...' -ForegroundColor Yellow
        try { $aTok = "$((Get-PimEpInteractiveToken -ClientId (Get-PimEpAzurePowerShellClientId) -Scopes @((Get-PimEpArmScope)) -Tenant $tenant -UseEdge $UseEdge -LoginHint $account).access_token)" }
        catch { throw ("Azure sign-in failed: $($_.Exception.Message)`n$(Get-PimEpBrokenAuthHelp)") }
    }
    [void](& $assertTenant $aTok 'Azure')
    Set-PimEpToken -Api arm -AccessToken $aTok
    foreach ($r in @(Invoke-PimEpAzureRoleGrant -EngineObjectId $EngineObjectId -Specs $azSpecs.ToArray() -PlanOnly:$previewOnly)) { $results.Add($r) }
}

# ---- report -------------------------------------------------------------------------------------------------------------
Write-Host ''
Write-Host $(if ($previewOnly) { 'Plan (nothing was changed):' } else { 'Result:' }) -ForegroundColor Cyan
foreach ($l in @(Format-PimEpResults -Results $results.ToArray())) {
    $color = if ($l -match '^\s+refused') { 'Red' } elseif ($l -match '^\s+granted') { 'Green' } else { 'Gray' }
    Write-Host $l -ForegroundColor $color
}
if ($WhatIfPreference) {
    # PowerShell's own "What if:" line for every grant the run would make (ShouldProcess answers $false under -WhatIf).
    foreach ($w in @($results | Where-Object { $_.status -eq 'would grant' })) {
        $target = if ($w.kind -eq 'Azure role') { "engine identity $EngineObjectId at Azure scope $($w.where)" } else { "engine identity $EngineObjectId on $($w.where)" }
        $action = if ($w.kind -eq 'Azure role') { "assign Azure role '$($w.what)'" } else { "grant application permission $($w.what)" }
        [void]$PSCmdlet.ShouldProcess($target, $action)
    }
    if (-not @($results | Where-Object { $_.status -eq 'would grant' }).Count) { Write-Host 'What if: nothing to grant -- the engine identity already holds everything asked for (or it was refused above).' }
}
$refused = @($results | Where-Object { $_.status -eq 'refused' }).Count
$granted = @($results | Where-Object { $_.status -eq 'granted' }).Count
Write-Host ''
if ($granted) { Write-Host "A new grant reaches the engine's token within about 30 minutes. Then press Verify permissions in PIM Manager." -ForegroundColor Yellow }
if ($refused) { Write-Host "$refused permission(s) were refused -- see the reasons above." -ForegroundColor Red }
if ($PassThru) { $results.ToArray() }
if ($refused) { exit 1 }
} finally { Stop-PimScriptRun -Script 'Grant-PimEnginePermissions' }