internal/functions/core/Invoke-EntraRequest.ps1

function Invoke-EntraRequest {
    <#
    .SYNOPSIS
        Executes a web request against an entra-based service
    
    .DESCRIPTION
        Executes a web request against an entra-based service
        Handles all the authentication details once connected using Connect-EntraService.

        Vendored from EntraAuth, with changes of this module - keep them when syncing with upstream
        (docs/internal/entraauth-divergence.md):
        - the access token goes only over https and only to the host of the service the token belongs to: every
          URL - a relative path, an absolute -Path, each @odata.nextLink - is checked before it is sent
          (Assert-EntraAuthorizedUri), and another host or http stops the request with a SecurityError before
          anything is sent;
        - request URLs are logged without their query (Get-EntraLogUri), since they carry delta and skip tokens,
          and the messages use this module's localized strings (Write-PSFMessage -String);
        - the delta token is parsed pair by pair and decoded (see the comments below);
        - every page is sent through the one retry policy of the module (Invoke-EntraRetry, Settings.Request.RetryCount,
          default 5): 408, 429 and 5xx except 501 and 505 and no answer at all are repeated for GET, PUT, PATCH, DELETE,
          HEAD and OPTIONS; any other method (a POST) only on 429 and 503, where the service says it did not carry the
          request out. A 400 whose Graph error code is Directory_ConcurrencyViolation is repeated for every method. The wait is the Retry-After of the answer (seconds or an HTTP date, at most 5 minutes), otherwise
          2^attempt seconds with jitter. A failed page is repeated on its own: the pages before it are not sent or
          emitted again. Nothing above this function retries, so a page is sent at most RetryCount + 1 times;
        - every request may take Settings.Request.TimeoutSeconds (default 600, 0 = no limit).
    
    .PARAMETER Path
        The relative path of the endpoint to query.
        For example, to retrieve Microsoft Graph users, it would be a plain "users".
        To access details on a particular defender for endpoint machine instead it would look thus: "machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
        An absolute URL is accepted only when it is https on the host of the token's service URL; any other is
        refused before anything is sent.
    
    .PARAMETER Body
        Any body content needed for the request.

    .PARAMETER Query
        Any query content to include in the request.
        In opposite to -Body this is attached to the request Url and usually used for filtering.
    
    .PARAMETER Method
        The Rest Method to use.
        Defaults to GET
    
    .PARAMETER RequiredScopes
        Any authentication scopes needed.
        Used for documentary purposes only.

    .PARAMETER Header
        Any additional headers to include on top of authentication and content-type.

    .PARAMETER ContentType
        Specify the content-type of this request.
        Equivalent to specifying it as a header entry, but added as dedicated parameter for user convenience.
    
    .PARAMETER Service
        Which service to execute against.
        Determines the API endpoint called to.
        Defaults to "Graph"

    .PARAMETER SerializationDepth
        How deeply to serialize the request body when converting it to json.
        Defaults to: 99

    .PARAMETER Token
        A Token as created and maintained by this module.
        If specified, it will override the -Service parameter.

    .PARAMETER NoPaging
        Do not automatically page through responses sets.
        By default, Invoke-EntraRequest is going to keep retrieving result pages until all data has been retrieved.

    .PARAMETER Raw
        Do not process the response object and instead return the raw result returned by the API.

    .PARAMETER DeltaSession
        A hashtable including delta sessions.
        Use together with the delta endpoints, e.g. for the Graph API's user delta endpoint:
        https://learn.microsoft.com/en-us/graph/api/user-delta
        Provide an empty hashtable on the first request, the delta token data will be inserted into it.
        Provide the same token for subsequent delta requests.

        This allows retrieving changes over time, without having to reload the entire dataset.

    .PARAMETER MinimalDelta
        When receiving delta data, only return the changed properties (plus a unique identifier), rather than the full object.
        Only used together with DeltaSession
    
    .EXAMPLE
        PS C:\> Invoke-EntraRequest -Path 'alerts' -RequiredScopes 'Alert.Read'
    
        Return a list of defender alerts.

    .EXAMPLE
        PS C:\> Invoke-EntraRequest -Path 'users/delta' -DeltaSession $delta

        Retrieves all users on first request.
        Subsequent calls will only return users that have been changed in the meantime.
#>

    [CmdletBinding(DefaultParameterSetName = 'default')]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Path,
        
        $Body,

        [Hashtable]
        $Query = @{ },
        
        [string]
        $Method = 'GET',
        
        [string[]]
        $RequiredScopes,

        [hashtable]
        $Header = @{},

        [string]
        $ContentType,
        
        [ArgumentCompleter({ Get-ServiceCompletion $args })]
        [ValidateScript({ Assert-ServiceName -Name $_ -IncludeTokens })]
        [string]
        $Service = $script:_DefaultService,

        [ValidateRange(1, 666)]
        [int]
        $SerializationDepth = 99,

        [EntraToken]
        $Token,

        [switch]
        $NoPaging,

        [switch]
        $Raw,

        [hashtable]
        $DeltaSession,

        [switch]
        $MinimalDelta
    )
    
    DynamicParam {
        if ($Resource) { return }

        $actualService = $Service
        if (-not $actualService) { $actualService = $script:_DefaultService }
        $serviceObject = $script:_EntraEndpoints.$actualService
        if (-not $serviceObject) { return }
        if ($serviceObject.Parameters.Count -lt 1) { return }

        $results = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
        foreach ($pair in $serviceObject.Parameters.GetEnumerator()) {
            $parameterAttribute = [System.Management.Automation.ParameterAttribute]::new()
            $parameterAttribute.ParameterSetName = '__AllParameterSets'
            $parameterAttribute.Mandatory = $true
            $parameterAttribute.HelpMessage = $pair.Value
            $attributesCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
            $attributesCollection.Add($parameterAttribute)
            $RuntimeParam = [System.Management.Automation.RuntimeDefinedParameter]::new($pair.Key, [object], $attributesCollection)

            $results.Add($pair.Key, $RuntimeParam)
        }

        $results
    }

    begin {
        if ($Token) {
            $tokenObject = $Token
        }
        else {
            Assert-EntraConnection -Service $Service -Cmdlet $PSCmdlet -RequiredScopes $RequiredScopes
            $tokenObject = $script:_EntraTokens.$Service
        }
        
        $serviceObject = $script:_EntraEndpoints.$($tokenObject.Service)
        if ($ContentType) { $Header['Content-Type'] = $ContentType }
    }
    process {
        $parameters = @{
            Method = $Method
            Uri    = Resolve-RequestUri -TokenObject $tokenObject -ServiceObject $serviceObject -BoundParameters $PSBoundParameters
        }
        $originalUri = $parameters.Uri
        # The URL the token belongs to, its parameters resolved as Resolve-RequestUri does: every request of this call -
        # the first, each next link - must stay on its scheme, host and port.
        [string] $authorizedUrl = Resolve-EntraServiceUrl -TokenObject $tokenObject -ServiceObject $serviceObject -BoundParameters $PSBoundParameters
        
        if ($PSBoundParameters.Keys -contains 'Body') {
            if ($Body -is [string]) {
                $parameters.Body = $Body
            }
            else {
                $parameters.Body = $Body | ConvertTo-Json -Compress -Depth $SerializationDepth
            }
        }
        # In PS5.1, some methods cannot contain a body
        $noBodyMethods = 'Default', 'Get', 'Head'
        if ($PSVersionTable.PSVersion.Major -lt 6 -and $Method -in $noBodyMethods) {
            $parameters.Remove('Body')
        }
        
        $queryClone = $Query.Clone()
        if ($DeltaSession -and $DeltaSession[$originalUri].Token) {
            $queryClone['$deltaToken'] = $DeltaSession[$originalUri].Token
        }
        $parameters.Uri += ConvertTo-QueryString -QueryHash $queryClone -DefaultQuery $tokenObject.Query

        # The one retry layer (Invoke-EntraRetry). A method that may have changed something - a POST - is repeated only
        # when the service said it did not carry it out (429, 503); the others set the same state again.
        [bool] $requestNotIdempotent = $Method.ToUpperInvariant() -notin 'GET', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'
        [int] $requestTimeout = Get-PSFConfigValue -FullName 'PSMicrosoftEntraID.Settings.Request.TimeoutSeconds' -Fallback 600
        if ($requestTimeout -gt 0) { $parameters.TimeoutSec = $requestTimeout }
        # Read by the script block below under names of their own: it runs in a scope below Invoke-EntraRetry.
        $requestToken = $tokenObject
        $requestHeader = $Header
        [bool] $requestMinimal = $MinimalDelta.IsPresent

        do {
            # Before the header is built: an absolute -Path or a next link on another host, or over http, never gets
            # the token. A terminating SecurityError. Checked once per page: a repetition goes to the same URL.
            Assert-EntraAuthorizedUri -Uri $parameters.Uri -ServiceUrl $authorizedUrl -Cmdlet $PSCmdlet
            # Scheme, host and path only: the query carries delta and skip tokens.
            Write-PSFMessage -Level Verbose -String 'Request.Execute' -StringValues $Method, (Get-EntraLogUri -Uri $parameters.Uri)
            try {
                $result = Invoke-EntraRetry -NotIdempotent:$requestNotIdempotent -ScriptBlock {
                    # A fresh header for every attempt: GetHeader() renews a token that expired while the request waited.
                    $requestTempHeader = $requestToken.GetHeader().Clone()
                    foreach ($requestPair in $requestHeader.GetEnumerator()) { $requestTempHeader[$requestPair.Key] = $requestPair.Value }
                    if ($requestMinimal) { $requestTempHeader['Prefer'] = 'return=minimal' }
                    $parameters.Headers = $requestTempHeader
                    Invoke-RestMethod @parameters -ErrorAction Stop
                }
            }
            catch {
                Write-PSFMessage -Level Warning -String 'Request.Failed' -StringValues $Method, (Get-EntraLogUri -Uri $parameters.Uri)
                $PSCmdlet.ThrowTerminatingError($_)
            }
            if (-not $Raw -and -not $tokenObject.RawOnly -and $result.PSObject.Properties.Where{ $_.Name -eq 'value' }) { $result.Value }
            else { $result }
            $parameters.Uri = $result.'@odata.nextLink'

            if ($DeltaSession -and $result.'@odata.deltaLink') {
                # Parse the query properly instead of splitting the whole link on '=' and
                # taking the last piece. That shortcut breaks on both shapes Graph
                # actually returns: a token carrying base64 '=' padding truncates to an
                # empty string, and a link where $deltatoken is not the final parameter
                # yields the value of whatever came last. Both fail silently - an empty
                # token makes every run a full read, a wrong one is sent back to Graph as
                # if it were real.
                $deltaToken = $null
                $queryPart = ([string]$result.'@odata.deltaLink' -split '\?', 2)[1]
                if ($queryPart) {
                    foreach ($pair in ($queryPart -split '&')) {
                        # Split on the FIRST '=' only: the name is ours to match, the
                        # value is opaque and may contain more of them.
                        $keyValue = $pair -split '=', 2
                        if ($keyValue.Count -eq 2 -and $keyValue[0] -in '$deltatoken', '%24deltatoken') {
                            # DECODED before storing. This substring is cut out of a URL,
                            # so whatever percent-encoding the link carried is still in
                            # it - and ConvertTo-QueryString now encodes every value on
                            # the way out. Storing the raw substring would double-encode
                            # on the next request ('%2B' -> '%252B') and hand Graph a
                            # corrupted token. Decode here, encode exactly once there.
                            $deltaToken = [uri]::UnescapeDataString($keyValue[1])
                            break
                        }
                    }
                }

                if ($deltaToken) {
                    if (-not $DeltaSession[$originalUri]) {
                        $DeltaSession[$originalUri] = @{}
                    }
                    $DeltaSession[$originalUri]['Token'] = $deltaToken
                }
                else {
                    # Keep whatever token we already had rather than replacing it with
                    # nothing: losing it costs a full re-read, and an empty one guarantees
                    # that re-read happens on every run from here on.
                    # The link by scheme, host and path only: whatever its query carries is a token.
                    Write-PSFMessage -Level Warning -String 'Request.DeltaLinkNoToken' -StringValues (Get-EntraLogUri -Uri ([string]$result.'@odata.deltaLink'))
                }
            }
        }
        while ($parameters.Uri -and -not $NoPaging)
    }
}