<#
.SYNOPSIS
    SecurityInsight Pro: the SQL server's Entra admin is ONE role-assignable group, named the same everywhere (#227).

.DESCRIPTION
    Operator rule 2026-10-03: "we need consistent naming ... one group per app and then the spn becomes member of that.
    this must be identically with any prod env". So the Pro SQL server's Entra admin is the group 'grp-si-sql-admins'
    (the same name in every environment and at every customer -- no environment or ring in it; PIM4EntraPS has
    'grp-pim-sql-admins'), never an SPN or a person directly. Whoever administers the database -- the setup /
    management SPN, the Invardia Support app at setup level -- is a MEMBER of the group.

    The group is ROLE-ASSIGNABLE (isAssignableToRole). An ordinary security group can be changed by anyone with Groups
    Administrator or User Administrator, and by its owners: any of them could add themselves and take over the
    SecurityInsight SQL store. Only Privileged Role Administrators (and Global Administrators) can change the members of
    a role-assignable group. The setting exists only at creation, so an existing group with this name that is NOT
    role-assignable is refused, never used, and the steps to recreate it are printed.

    Steps (idempotent; -WhatIf shows the plan):
      1. the group exists, role-assignable (security group, not mail-enabled) -- created when missing
      2. members: -MemberObjectIds, plus the server's CURRENT Entra admin when it is a user or an app (so switching
         never locks anyone out). A role-assignable group cannot contain groups: when the current admin is another
         group, its members are passed with -MemberObjectIds and the switch confirmed with -ReplaceCurrentAdminGroup.
      3. the server's Entra admin = the group (Entra-only authentication stays on)
      4. the server records that admin AS A GROUP (a server made with a person or an application as its admin keeps that
         kind otherwise, and the group's members are then not let in) -- set when it is not, and read back
      5. framework §4.5 G3a -- a MOVE from another admin group (-ReplaceCurrentAdminGroup) at an install that has the
         database setup job: its identity is made a member of the new group too, and right after the move a run of the
         job must sign in THROUGH the new group (a managed identity's token keeps its old group claims for up to 24 hours;
         the run is started again after 5 and 10 minutes). It does not -> the server's administrator is put back as it
         was (read back) and the run stops, saying so. A membership of the new group 24 hours old needs no proof.
    Members are only ever ADDED here; nothing takes a member out of the group.
    Existing database users (the engine identity, the identity ledger's users) are untouched.

    RIGHTS. Creating a role-assignable group, and adding members to it, needs Privileged Role Administrator (or Global
    Administrator) for a person, or Microsoft Graph RoleManagement.ReadWrite.Directory (with Group.ReadWrite.All) for an
    app. Changing the SQL server's Entra admin needs Contributor on the server.

.EXAMPLE
    .\Set-SISqlAdminGroup.ps1 -SqlServerName sql-si-prod-pro-ca -ResourceGroupName rg-si-prod-pro-ca

.LINK
    https://invardia.com/docs/si/scripts/Set-SISqlAdminGroup/

.NOTES
    Requirements:
      PowerShell 7 (pwsh). Windows PowerShell 5.1 is refused at once (#Requires -Version 7.0).
      Role: Privileged Role Administrator (or Global Administrator) -- on the tenant
      Role: SQL Server Contributor (or Contributor / Owner) -- on the SQL server
      Role: Microsoft Graph RoleManagement.ReadWrite.Directory with Group.ReadWrite.All (when an app runs it instead of a person) -- on the tenant
      Hosts: *.blob.core.windows.net, *.queue.core.windows.net, *.table.core.windows.net, *.vault.azure.net, 169.254.169.254, api.loganalytics.io, graph.microsoft.com, invardia.com, login.microsoftonline.com, management.azure.com, monitor.azure.com, outlook.office.com, outlook.office365.com, storage.azure.com, vault.azure.net
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][string]$SqlServerName,
    [Parameter(Mandatory)][string]$ResourceGroupName,
    [string]$SubscriptionId,
    [string[]]$MemberObjectIds = @(),
    [string]$GroupName = 'grp-si-sql-admins',
    # the display name a NEW group is created with (default: -GroupName). CR5: a new install passes 'SecurityInsight SQL admins';
    # the mailNickname always follows -GroupName, so every later run finds the group under either name.
    [string]$DisplayName = '',
    # The server's current admin is ANOTHER group (for example the group this one replaces). A role-assignable group
    # cannot contain it, so its members must be in -MemberObjectIds; this switch confirms that they are.
    [switch]$ReplaceCurrentAdminGroup
)

#Requires -Version 7.0
# SecurityInsight 3.0.79 -- Set-SISqlAdminGroup.ps1, standalone (Community edition). Built 2026-11-09T20:28:39Z from commit c1472e2f4c240c971c9559f07eef7e794b322001, source SOLUTIONS/SecurityInsight/setup/Set-SISqlAdminGroup.ps1,
# by release/Build-SISupportScripts.ps1 (framework SUPPORT-DL-1). Download: Invoke-WebRequest https://invardia.com/support/si/Set-SISqlAdminGroup.ps1 -OutFile Set-SISqlAdminGroup.ps1
# It carries the 16 SecurityInsight file(s) the script loads (listed in $__siSupportFiles below, readable, each line
# prefixed with "|"); at run time it writes them to a private temporary folder, checks each SHA-256, runs the original
# script from there with your parameters, and removes the folder. No PowerShell modules are needed.
$script:SIScriptVersion = '3.0.79'   # SI #547: the version this copy reports first (stamped into its embedded setup/_shared/SI-ScriptRun.ps1 too)
$__siSupportVersion = '3.0.79'
$__siSupportEntry = 'setup/Set-SISqlAdminGroup.ps1'
$__siSupportFiles = [ordered]@{}
$__siSupportFiles['setup/Set-SISqlAdminGroup.ps1'] = @{ Sha256 = '6b0b359da2b8df6e94f626e056cfc762540f40cb5a508c0e1b1446a67971b297'; Text = @'
|<#
|.SYNOPSIS
|    SecurityInsight Pro: the SQL server's Entra admin is ONE role-assignable group, named the same everywhere (#227).
|
|.DESCRIPTION
|    Operator rule 2026-10-03: "we need consistent naming ... one group per app and then the spn becomes member of that.
|    this must be identically with any prod env". So the Pro SQL server's Entra admin is the group 'grp-si-sql-admins'
|    (the same name in every environment and at every customer -- no environment or ring in it; PIM4EntraPS has
|    'grp-pim-sql-admins'), never an SPN or a person directly. Whoever administers the database -- the setup /
|    management SPN, the Invardia Support app at setup level -- is a MEMBER of the group.
|
|    The group is ROLE-ASSIGNABLE (isAssignableToRole). An ordinary security group can be changed by anyone with Groups
|    Administrator or User Administrator, and by its owners: any of them could add themselves and take over the
|    SecurityInsight SQL store. Only Privileged Role Administrators (and Global Administrators) can change the members of
|    a role-assignable group. The setting exists only at creation, so an existing group with this name that is NOT
|    role-assignable is refused, never used, and the steps to recreate it are printed.
|
|    Steps (idempotent; -WhatIf shows the plan):
|      1. the group exists, role-assignable (security group, not mail-enabled) -- created when missing
|      2. members: -MemberObjectIds, plus the server's CURRENT Entra admin when it is a user or an app (so switching
|         never locks anyone out). A role-assignable group cannot contain groups: when the current admin is another
|         group, its members are passed with -MemberObjectIds and the switch confirmed with -ReplaceCurrentAdminGroup.
|      3. the server's Entra admin = the group (Entra-only authentication stays on)
|      4. the server records that admin AS A GROUP (a server made with a person or an application as its admin keeps that
|         kind otherwise, and the group's members are then not let in) -- set when it is not, and read back
|      5. framework §4.5 G3a -- a MOVE from another admin group (-ReplaceCurrentAdminGroup) at an install that has the
|         database setup job: its identity is made a member of the new group too, and right after the move a run of the
|         job must sign in THROUGH the new group (a managed identity's token keeps its old group claims for up to 24 hours;
|         the run is started again after 5 and 10 minutes). It does not -> the server's administrator is put back as it
|         was (read back) and the run stops, saying so. A membership of the new group 24 hours old needs no proof.
|    Members are only ever ADDED here; nothing takes a member out of the group.
|    Existing database users (the engine identity, the identity ledger's users) are untouched.
|
|    RIGHTS. Creating a role-assignable group, and adding members to it, needs Privileged Role Administrator (or Global
|    Administrator) for a person, or Microsoft Graph RoleManagement.ReadWrite.Directory (with Group.ReadWrite.All) for an
|    app. Changing the SQL server's Entra admin needs Contributor on the server.
|
|.EXAMPLE
|    .\Set-SISqlAdminGroup.ps1 -SqlServerName sql-si-prod-pro-ca -ResourceGroupName rg-si-prod-pro-ca
|
|.LINK
|    https://invardia.com/docs/si/scripts/Set-SISqlAdminGroup/
|#>
|[CmdletBinding(SupportsShouldProcess)]
|param(
|    [Parameter(Mandatory)][string]$SqlServerName,
|    [Parameter(Mandatory)][string]$ResourceGroupName,
|    [string]$SubscriptionId,
|    [string[]]$MemberObjectIds = @(),
|    [string]$GroupName = 'grp-si-sql-admins',
|    # the display name a NEW group is created with (default: -GroupName). CR5: a new install passes 'SecurityInsight SQL admins';
|    # the mailNickname always follows -GroupName, so every later run finds the group under either name.
|    [string]$DisplayName = '',
|    # The server's current admin is ANOTHER group (for example the group this one replaces). A role-assignable group
|    # cannot contain it, so its members must be in -MemberObjectIds; this switch confirms that they are.
|    [switch]$ReplaceCurrentAdminGroup
|)
|
|#Requires -Version 7.0   # after the help and the param block: before the help, it hides the help from Get-Help
|# framework section 12.7 / 12.10: the documentation link first, a transcript of the run, -WhatIf writes nothing
|. ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-ScriptRun.ps1'))
|$siRun = Start-SIScriptRun -Script 'Set-SISqlAdminGroup' -Quiet:($false)
|try {
|$ErrorActionPreference = 'Stop'
|# Azure over native REST, no PowerShell module (#305). An existing sign-in in this process (the guided install) is reused;
|# otherwise a person signs in here (Azure Cloud Shell, or the browser).
|if (-not (Get-Command -Name Get-SISetupAzureContext -ErrorAction SilentlyContinue)) { . ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-SetupAzure.ps1')) }
|# #548: this script calls Invoke-SIRestMethod (engine\_shared\SI-AzRest.ps1, which publishes it globally). When the sign-in
|# above came from a caller that did not load the REST layer, load it here -- in a child scope, so only the published
|# Invoke-SIRestMethod arrives and nothing the caller already has (its own token or ARM helpers) is replaced.
|if (-not (Get-Command -Name Invoke-SIRestMethod -ErrorAction SilentlyContinue)) {
|    & { . ([IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'engine', '_shared', 'SI-AzRest.ps1')) }
|}
|$azCtx = Get-SISetupAzureContext
|if (-not $azCtx) { $azCtx = Connect-SISetupAzure -SubscriptionId $SubscriptionId }
|if (-not $SubscriptionId) { $SubscriptionId = [string]$azCtx.Subscription.Id }
|$t = [string](Get-SIAzureToken -Audience Graph)
|$hdr = @{ Authorization = 'Bearer ' + $t }
|function Graph([string]$Method, [string]$Url, $Body) {
|    $a = @{ Method = $Method; Uri = $Url; Headers = $hdr }
|    if ($null -ne $Body) { $a.ContentType = 'application/json'; $a.Body = ($Body | ConvertTo-Json -Compress -Depth 5) }
|    Invoke-SIRestMethod @a   # #548: through the support recorder in a support session
|}
|# #695: a new Entra admin is waited for until Azure has FINISHED the write (setup\_shared\SI-SqlAdminReady.ps1)
|. ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-SqlAdminReady.ps1'))
|# #1092: a member added right after the group was made waits out Entra replication, then is read back
|. ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-GroupMemberAdd.ps1'))
|# framework §4.5 G3a: a move from one admin GROUP to another is proven by the database setup job (setup\_shared\SI-DbInitJob.ps1)
|. ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-DbInitJob.ps1'))
|$siArm = {
|    param([string]$Method, [string]$Path, $Body)
|    $a = @{ Method = $Method; Path = $Path }
|    if ($null -ne $Body) { $a.Payload = ($Body | ConvertTo-Json -Depth 30 -Compress) }
|    $r = Invoke-SIAzRestMethod @a
|    if ($Method -eq 'GET' -and [int]$r.StatusCode -eq 404) { return $null }
|    if ([int]$r.StatusCode -ge 300) { throw ('{0} {1} failed ({2}): {3}' -f $Method, ($Path -replace '\?.*$', ''), $r.StatusCode, $r.Content) }
|    if ("$($r.Content)".Trim()) { $r.Content | ConvertFrom-Json }
|}
|$siAdminRest = { param([string]$Method, [string]$Path) Invoke-SIAzRestMethod -Method $Method -Path $Path }
|$siAdminPrint = { param([string]$Text) Write-Host $Text -ForegroundColor DarkYellow }
|$serverPath = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Sql/servers/{2}' -f $SubscriptionId, $ResourceGroupName, $SqlServerName
|$adminPath = $serverPath + '/administrators/ActiveDirectory?api-version=2021-11-01'
|Write-Host ("SecurityInsight -- SQL Entra admin group '{0}' for {1}{2}" -f $GroupName, $SqlServerName, $(if ($WhatIfPreference) { ' -- plan only (-WhatIf)' } else { '' }))
|$selfCmd = '.\setup\Set-SISqlAdminGroup.ps1 -SqlServerName {0} -ResourceGroupName {1}' -f $SqlServerName, $ResourceGroupName
|
|# ---- 1. the group (role-assignable, or refused) ----
|# CR5 (#655 item 5): found under ANY of its names -- grp-si-sql-admins, its display name "SecurityInsight SQL admins" after
|# the rename, or its mailNickname -- never by one display name alone: a renamed group would not be found and a second one
|# would be created (setup\_shared\SI-DisplayNames.ps1, Find-SISqlAdminGroup).
|. ([IO.Path]::Combine($PSScriptRoot, '_shared', 'SI-DisplayNames.ps1'))
|$fg = Find-SISqlAdminGroup -Graph { param($m, $u, $b) Graph $m $u $b } -GroupName $GroupName
|if ($fg.Count -gt 1) { throw ("{0} groups are named '{1}' (or carry its other name) -- resolve that by hand first: {2}" -f $fg.Count, $GroupName, ($fg.Ids -join ', ')) }
|$grp = $fg.Group
|if ($grp -and $grp.DisplayName -cne $GroupName) { Write-Host ('  [present ] the group {0} is shown as "{1}"' -f $GroupName, $grp.DisplayName) }
|if ($grp -and -not [bool]$grp.isAssignableToRole) {
|    $temp = '{0}-new' -f $GroupName
|    $steps = @(
|        ("The group '{0}' ({1}) is NOT role-assignable, so it is not used and no member is added." -f $GroupName, $grp.id),
|        'Anyone with Groups Administrator or User Administrator, or an owner of the group, could add themselves to it and administer the SecurityInsight SQL store.',
|        'Role-assignable can only be set when a group is created. Recreate it (needs Privileged Role Administrator):',
|        '  1. List the old group''s members (service principals too -- a listing can leave them out; add the setup and management identities yourself):',
|        ('       Microsoft Entra admin center: Groups > All groups > {0} > Members (note each member''s Object ID)' -f $grp.id),
|        '  2. Create the role-assignable group under a temporary name and point the server at it:',
|        ('       {0} -GroupName ''{1}'' -MemberObjectIds <the ids from step 1> -ReplaceCurrentAdminGroup' -f $selfCmd, $temp),
|        '  3. Delete the old group:',
|        ('       Microsoft Entra admin center: Groups > All groups > {0} > Delete' -f $grp.id),
|        ('  4. Give the new group the standard name (its id is printed by step 2), then confirm:'),
|        ('       Microsoft Entra admin center: Groups > All groups > <new-group-id> > Properties > Group name = {0} > Save' -f $GroupName),
|        ('       {0}' -f $selfCmd),
|        ('  If no SQL server uses the old group: delete it (step 3) and re-run {0}' -f $selfCmd)
|    )
|    foreach ($l in $steps) { Write-Host $l -ForegroundColor Yellow }
|    throw ("The group '{0}' is not role-assignable and must be recreated -- the steps are printed above." -f $GroupName)
|}
|if ($grp) { Write-Host ('  [present ] group {0} ({1}), role-assignable' -f $GroupName, $grp.id) }
|elseif ($PSCmdlet.ShouldProcess($GroupName, 'create role-assignable security group')) {
|    $nick = ($GroupName -replace '[^A-Za-z0-9]', '')
|    try {
|        $grp = Graph Post 'https://graph.microsoft.com/v1.0/groups' @{ displayName = $(if ("$DisplayName".Trim()) { "$DisplayName".Trim() } else { $GroupName }); mailEnabled = $false; mailNickname = $nick; securityEnabled = $true
|            isAssignableToRole = $true
|            description = 'SecurityInsight Pro: the Entra admin of the SecurityInsight SQL server(s). Members administer the Pro database. Role-assignable: only Privileged Role Administrators change its members.' }
|    } catch {
|        throw ("Creating the role-assignable group '{0}' failed: {1}. It needs Privileged Role Administrator (or Global Administrator), or RoleManagement.ReadWrite.Directory for an app." -f $GroupName, $_.Exception.Message)
|    }
|    Write-Host ('  [created ] group {0} ({1}), role-assignable' -f $GroupName, $grp.id)
|    # a new directory object answers 404 for a few seconds (replication) -- wait until it is readable
|    foreach ($i in 1..24) { try { $null = Graph Get "https://graph.microsoft.com/v1.0/groups/$($grp.id)?`$select=id" $null; break } catch { Start-Sleep -Seconds 5 } }
|} else { Write-Host ('  [plan    ] create role-assignable group {0}' -f $GroupName) }
|
|# ---- 2. members (the current admin first, so the switch never locks anyone out) ----
|$cur = $null
|try { $cur = (Invoke-SIAzRestMethod -Method GET -Path $adminPath).Content | ConvertFrom-Json } catch { }
|$curSid = if ($cur -and $cur.properties) { [string]$cur.properties.sid } else { '' }
|$want = New-Object System.Collections.Generic.List[string]
|if ($curSid -and (-not $grp -or $curSid -ne [string]$grp.id)) {
|    # the current admin's sid is an object id for a user/group; for an app it is the app's client id -> its SP object id
|    $curObj = $null; $curType = ''
|    try { $o = Graph Get "https://graph.microsoft.com/v1.0/directoryObjects/$curSid" $null; $curObj = $o.id; $curType = [string]$o.'@odata.type' } catch { }
|    if (-not $curObj) { try { $curObj = @((Graph Get "https://graph.microsoft.com/v1.0/servicePrincipals?`$filter=appId eq '$curSid'&`$select=id" $null).value)[0].id } catch { } }
|    if ($curType -eq '#microsoft.graph.group') {
|        # A role-assignable group cannot contain a group. Its members must be carried over by hand -- never guessed from
|        # a listing, which can leave service principals out.
|        if (-not $ReplaceCurrentAdminGroup) {
|            Write-Host ("The server's admin today is the group '{0}' ({1}). A role-assignable group cannot contain it." -f $cur.properties.login, $curSid) -ForegroundColor Yellow
|            Write-Host ('  1. List its members -- Microsoft Entra admin center: Groups > All groups > {0} > Members (note each Object ID; add the setup and management identities if they are missing)' -f $curSid) -ForegroundColor Yellow
|            Write-Host ('  2. Re-run: {0} -MemberObjectIds <those ids> -ReplaceCurrentAdminGroup' -f $selfCmd) -ForegroundColor Yellow
|            throw ("The server's admin is another group ('{0}'): pass its members with -MemberObjectIds and confirm with -ReplaceCurrentAdminGroup." -f $cur.properties.login)
|        }
|        if (@($MemberObjectIds | Where-Object { $_ }).Count -eq 0) { throw '-ReplaceCurrentAdminGroup needs -MemberObjectIds: the members that keep administering the database.' }
|        Write-Host ('  [replace ] the current admin group {0} -- its members come from -MemberObjectIds' -f $cur.properties.login)
|        # framework §4.5 G3a: the database setup job signs in through the admin group -- its identity becomes a member of the
|        # new group too, and the move is proven by a run of it (below)
|        $dbn = Get-SIDbInitNames
|        $jobMi = $null; try { $jobMi = & $siArm 'GET' ('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{2}?api-version={3}' -f $SubscriptionId, $ResourceGroupName, $dbn.Identity, $dbn.MiApi) $null } catch { $jobMi = $null }
|        $jobPid = [string](Get-SIDbInitProp $jobMi @('properties', 'principalId'))
|        if ($jobPid) {
|            $siMoveJob = $null; try { $siMoveJob = & $siArm 'GET' ('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.App/jobs/{2}?api-version={3}' -f $SubscriptionId, $ResourceGroupName, $dbn.Job, $dbn.AppApi) $null } catch { $siMoveJob = $null }
|            $siMovePid = $jobPid
|            if (-not $MemberObjectIds -or @($MemberObjectIds) -notcontains $jobPid) { $MemberObjectIds = @($MemberObjectIds) + @($jobPid) }
|            Write-Host ('  [member  ] the database setup job''s identity {0} ({1}) is made a member of {2} too' -f $dbn.Identity, $jobPid, $GroupName)
|        }
|        $siMoveFrom = 'group'
|    } elseif ($curObj) { $want.Add([string]$curObj) }
|    else { Write-Warning "the current admin ($($cur.properties.login)) could not be resolved -- add it to the group by hand before switching" }
|}
|foreach ($m in $MemberObjectIds) { if ($m -and -not $want.Contains($m)) { $want.Add($m) } }
|foreach ($m in $want) {
|    # asked from the MEMBER's side: a plain /members listing leaves service principals out for many callers (seen live
|    # 2026-10-03), so a real member read as missing and the re-add failed
|    $isMember = $false
|    if ($grp -and $grp.id) { try { $isMember = @((Graph Post "https://graph.microsoft.com/v1.0/directoryObjects/$m/checkMemberGroups" @{ groupIds = @([string]$grp.id) }).value) -contains [string]$grp.id } catch { } }
|    if ($isMember) { Write-Host ('  [present ] member {0}' -f $m); continue }
|    if ($grp -and $grp.id -and $PSCmdlet.ShouldProcess($m, "add to $GroupName")) {
|        # A group (or a member) created seconds ago answers "not found" for a moment: ONLY that answer is waited for and
|        # the add tried again HERE -- never by running the whole script again, whose look-up by name could miss the new
|        # group and create a second one. A refusal stops at once, with its reason. #1092: the wait grows up to a stated
|        # limit (5 minutes, said in the log line), and the membership is READ BACK from the member's side.
|        $memberAdd = Invoke-SIGroupMemberAddRetry -What ('member ' + $m) -LimitSeconds 300 `
|            -Add { Graph Post "https://graph.microsoft.com/v1.0/groups/$($grp.id)/members/`$ref" @{ '@odata.id' = "https://graph.microsoft.com/v1.0/directoryObjects/$m" } | Out-Null } `
|            -Test { @((Graph Post "https://graph.microsoft.com/v1.0/directoryObjects/$m/checkMemberGroups" @{ groupIds = @([string]$grp.id) }).value) -contains [string]$grp.id }
|        switch ($memberAdd.State) {
|            'refused' { throw ("adding {0} to the group '{1}' was refused: {2}" -f $m, $GroupName, $memberAdd.Error) }
|            'notfound' { throw ("adding {0} to the group '{1}' failed: {2} -- run the same command again in a few minutes." -f $m, $GroupName, $memberAdd.Detail) }
|            'unchecked' { Write-Host ('  [added   ] member {0} -- {1}' -f $m, $memberAdd.Detail) -ForegroundColor Yellow }
|            default { Write-Host ('  [added   ] member {0} (read back{1})' -f $m, $(if ($memberAdd.WaitedSeconds) { ', after {0} s of Entra replication' -f $memberAdd.WaitedSeconds } else { '' })) }
|        }
|    } else { Write-Host ('  [plan    ] add member {0}' -f $m) }
|}
|
|# ---- G3a: is this a move the database setup job must prove? (the server's administrators block kept for a rollback) ----
|$siMovePlan = $null; $siMovePrev = $null
|if ($grp -and $grp.id -and $siMoveFrom) {
|    $since = $null
|    if ($siMovePid) { try { $pa = Get-SIDbInitPimAssignment -Graph { param($m, $u, $b) Graph $m $u $b } -PrincipalId $siMovePid -GroupId ([string]$grp.id); if ($pa.Found -and $pa.Start) { $since = $pa.Start } } catch { } }
|    $siMovePlan = Get-SISqlAdminMovePlan -CurrentSid $curSid -CurrentKind $siMoveFrom -NewGroupId ([string]$grp.id) -JobExists ([bool]$siMoveJob) -MemberSince $since
|    Write-Host ('  [move    ] {0}' -f $siMovePlan.Detail)
|    if ($siMovePlan.Action -eq 'verify') {
|        $siSrv = $null; try { $siSrv = & $siArm 'GET' ($serverPath + '?api-version=2021-11-01') $null } catch { $siSrv = $null }
|        $siMovePrev = Get-SIDbInitProp $siSrv @('properties', 'administrators')
|        if (-not $siMovePrev) { throw 'the server''s administrator before the move could not be read, so the move could not be undone if the database setup job cannot sign in through the new group -- nothing was moved; run this again' }
|    }
|}
|
|# ---- 3. the server's Entra admin = the group ----
|$curLogin = if ($cur -and $cur.properties) { [string]$cur.properties.login } else { '' }
|# the login is only the server's label for the group: either of the group's two names is the group (CR5: renamed groups keep their login)
|if ($grp -and $grp.id -and $curSid -eq [string]$grp.id -and @(Get-SIDisplayNameAliases -Role SqlAdminGroup -Name $GroupName) -contains $curLogin) { Write-Host ('  [present ] {0} is the Entra admin of {1}' -f $GroupName, $SqlServerName) }
|elseif ($grp -and $grp.id -and $PSCmdlet.ShouldProcess($SqlServerName, "set Entra admin = $GroupName")) {
|    $tenant = [string]$azCtx.Tenant.Id
|    $body = @{ properties = @{ administratorType = 'ActiveDirectory'; login = $GroupName; sid = [string]$grp.id; tenantId = $tenant } } | ConvertTo-Json -Depth 4
|    $r = Invoke-SIAzRestMethod -Method PUT -Path $adminPath -Payload $body
|    if ($r.StatusCode -ge 300) { throw ("setting the Entra admin failed ({0}): {1}" -f $r.StatusCode, $r.Content) }
|    # #695 (customer B 2026-10-15): Azure answers this write Accepted and finishes it seconds later, while the admin
|    # already READS BACK as set -- a sign-in in between was refused. Wait until Azure has FINISHED the write, then read back.
|    $null = Wait-SISqlAdminWrite -Response $r -Rest $siAdminRest -AdminPath $adminPath -Sid ([string]$grp.id) -Login $GroupName `
|        -TimeoutSec 600 -PollSec 10 -Print $siAdminPrint -What ('the new Entra admin of {0}' -f $SqlServerName)
|    Write-Host ('  [set     ] {0} is now the Entra admin of {1} (was {2})' -f $GroupName, $SqlServerName, $(if ($cur) { $cur.properties.login } else { 'none' }))
|} else { Write-Host ('  [plan    ] set Entra admin of {0} = {1}' -f $SqlServerName, $GroupName) }
|
|# ---- 4. the server records that admin AS A GROUP ----
|# Step 3 names the group through the server's administrators resource, which has no field for the KIND. A server that was
|# made with a person or an application as its admin keeps that kind although the group is named there now -- and Azure
|# SQL then does not let the group's MEMBERS in (an application was refused on 2026-10-12; with the kind Group the same
|# application was let in on 2026-10-13). The kind is on the SERVER itself: read there, set there when it is not Group,
|# and read back. A server whose kind cannot be read is left as it is, and that is said.
|if ($grp -and $grp.id) {
|    $serverUri = $serverPath + '?api-version=2021-11-01'
|    $readAdmins = {
|        $s = $null; try { $s = (Invoke-SIAzRestMethod -Method GET -Path $serverUri).Content | ConvertFrom-Json } catch { $s = $null }
|        if ($s -and $s.PSObject.Properties['properties'] -and $s.properties -and $s.properties.PSObject.Properties['administrators']) { $s.properties.administrators } else { $null }
|    }
|    $adm = & $readAdmins
|    $admSid = if ($adm -and $adm.PSObject.Properties['sid']) { [string]$adm.sid } else { '' }
|    $admKind = if ($adm -and $adm.PSObject.Properties['principalType']) { [string]$adm.principalType } else { '' }
|    if ($admSid -ne [string]$grp.id) {
|        if ($WhatIfPreference) { Write-Host ('  [plan    ] record the Entra admin of {0} as a group' -f $SqlServerName) }
|        else { Write-Host ('  [note    ] the kind {0} records for its Entra admin could not be read -- it must be Group for the members of {1} to be let in' -f $SqlServerName, $GroupName) -ForegroundColor Yellow }
|    } elseif ($admKind -ieq 'Group') { Write-Host ('  [present ] {0} records its Entra admin as a group' -f $SqlServerName) }
|    elseif ($PSCmdlet.ShouldProcess($SqlServerName, "record the Entra admin $GroupName as a group")) {
|        $block = [ordered]@{ administratorType = 'ActiveDirectory'; principalType = 'Group'; login = $GroupName; sid = [string]$grp.id; tenantId = [string]$azCtx.Tenant.Id }
|        # the server's own "Entra-only sign-in" setting goes back exactly as it is: the block is written whole
|        if ($adm.PSObject.Properties['azureADOnlyAuthentication'] -and "$($adm.azureADOnlyAuthentication)" -ne '') { $block.azureADOnlyAuthentication = [bool]$adm.azureADOnlyAuthentication }
|        $r = Invoke-SIAzRestMethod -Method PATCH -Path $serverUri -Payload (@{ properties = @{ administrators = $block } } | ConvertTo-Json -Depth 5)
|        if ($r.StatusCode -ge 300) { throw ("recording the Entra admin as a group failed ({0}): {1}" -f $r.StatusCode, $r.Content) }
|        # #695: this write is asynchronous too -- waited until Azure has finished it, then read back
|        $null = Wait-SIArmAsyncOperation -Response $r -Rest $siAdminRest -TimeoutSec 600 -PollSec 10 -Print $siAdminPrint -What ('the change of the Entra admin of {0} to a group' -f $SqlServerName)
|        $back = $null
|        foreach ($i in 1..36) {
|            $back = & $readAdmins
|            if ($back -and [string]$back.sid -eq [string]$grp.id -and [string]$back.principalType -ieq 'Group') { break }
|            Start-Sleep -Seconds 5
|        }
|        if (-not ($back -and [string]$back.sid -eq [string]$grp.id -and [string]$back.principalType -ieq 'Group')) { throw ('the server still records its Entra admin as "{0}", not as a group -- check the server' -f $(if ($back) { [string]$back.principalType } else { 'unreadable' })) }
|        Write-Host ('  [set     ] {0} now records its Entra admin as a group (was "{1}")' -f $SqlServerName, $admKind)
|    } else { Write-Host ('  [plan    ] record the Entra admin of {0} as a group (it is "{1}")' -f $SqlServerName, $admKind) }
|}
|
|# ---- G3a: the move PROVEN -- the database setup job signs in through the new group, else the move is rolled back ----
|if ($siMovePlan -and $siMovePlan.Action -eq 'verify') {
|    if ($WhatIfPreference) { Write-Host '  [plan    ] a run of the database setup job proves the move (else it is rolled back)' }
|    else {
|        $proof = Test-SISqlAdminMoveSignIn -Arm $siArm -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroupName
|        if ($proof.Ok) { Write-Host ('  [proven  ] {0}' -f $proof.Detail) }
|        else {
|            Write-Host ('  [rollback] {0} -- the server''s administrator is put back' -f $proof.Detail) -ForegroundColor Yellow
|            $back = Restore-SISqlAdminBlock -Arm $siArm -ServerPath $serverPath -Previous $siMovePrev
|            throw ('The move of the Entra admin of {0} to {1} was ROLLED BACK: {2}; {3}. The database setup job''s token still carries only the old group (it keeps group claims for up to 24 hours): run this again later (after 24 hours it needs no proof).' -f $SqlServerName, $GroupName, $proof.Detail, $back.Detail)
|        }
|    }
|} elseif ($siMovePlan -and $siMovePlan.Action -eq 'settled') { Write-Host ('  [proven  ] {0}' -f $siMovePlan.Detail) }
|} finally { Stop-SIScriptRun -Run $siRun }
'@ }
$__siSupportFiles['setup/_shared/SI-ScriptRun.ps1'] = @{ Sha256 = 'a5c4d788d516521639611af43e1b88458216ce58bdb455885cac8e2a568afbd2'; Text = @'
|#Requires -Version 5.1
|<#
|    EVERY SCRIPT A PERSON RUNS (framework DOCS/REQUIREMENTS.md section 12.7 SCRIPT-DOC-1 + section 12.10 SECURITY-PACK-1; SI #481 / #484).
|    One helper, called first by each such script:
|
|      $siRun = Start-SIScriptRun -Script '<Script>'
|      try { ...the script... } finally { Stop-SIScriptRun -Run $siRun }
|
|    Start-SIScriptRun prints, as the script's FIRST line (SI #547, owner 2026-10-10: "do you provide the version in all
|    scripts, so i can troubleshoot better"):
|        <Script> version <version> - documentation: https://invardia.com/docs/si/scripts/<Script>/
|    (the page Invardia renders from the script's <Script>.doc.json). The transcript is started BEFORE that line is printed,
|    so the same line is also the first line of the transcript. The version (Get-SIScriptVersion), in this order:
|        1. the version stamped into a PUBLISHED copy: release\Build-SISupportScripts.ps1 rewrites the
|           $script:SIScriptVersionStamp line below in the copy of this file each self-contained script embeds;
|        2. the install / package / checkout this file sits in: BUILD.json (its display, e.g. 3.0.0-rc.12), else VERSION;
|        3. "unknown (not a released copy)".
|    It then says plainly when -WhatIf is on (nothing is changed). The transcript is a local file in ONE known folder:
|        Windows : %LOCALAPPDATA%\SecurityInsight\script-logs\<Script>-<yyyyMMdd-HHmmss>.log
|        others  : ~/.securityinsight/script-logs/<Script>-<yyyyMMdd-HHmmss>.log
|    Stop-SIScriptRun ends the transcript and prints its path. The transcript holds what the script printed -- the scripts
|    never print a secret value (section 12.10 "no secrets in, no secrets out"). A transcript that cannot be started (a host
|    without transcription, a read-only profile) is said and the script goes on: it never blocks the work.
|    The transcript and its folder are written even under -WhatIf (-WhatIf:$false): they are the record of what was
|    previewed, not a change to the customer's environment.
|    PowerShell 5.1: no ?. / ??, no ternary.
|#>
|
|# SI #547 -- the PUBLISH STAMP. Empty in the repository and the package; release\Build-SISupportScripts.ps1 writes the release
|# version here (Set-SIScriptVersionStamp) in the copy a self-contained script embeds. Keep this line's shape: the build
|# refuses to publish when it cannot find it.
|$script:SIScriptVersionStamp = '3.0.79'
|# the folder this helper lives in (setup\_shared) -- the solution root is two levels up
|$script:SIScriptRunHome = $PSScriptRoot
|
|function Get-SIScriptVersion {
|    <#
|        The version a person-run script reports. -Stamp (default: the publish stamp above) wins; else -SolutionRoot's
|        BUILD.json display / version, else its VERSION file; else 'unknown (not a released copy)'. Never throws.
|    #>
|    param([AllowEmptyString()][string]$Stamp = [string]$script:SIScriptVersionStamp, [AllowEmptyString()][string]$SolutionRoot = '')
|    if ("$Stamp".Trim()) { return "$Stamp".Trim() }
|    if (-not "$SolutionRoot".Trim() -and "$($script:SIScriptRunHome)".Trim()) {
|        try { $SolutionRoot = [IO.Path]::GetFullPath([IO.Path]::Combine([string]$script:SIScriptRunHome, '..', '..')) } catch { $SolutionRoot = '' }
|    }
|    if ("$SolutionRoot".Trim()) {
|        try {
|            # not [IO.Path]::Combine(..., 'BUILD.json'): the support-script builder embeds every data file a helper names that
|            # way, and a published copy must never carry the build machine's BUILD.json (its version comes from the stamp)
|            $bj = $SolutionRoot.TrimEnd('\', '/') + [IO.Path]::DirectorySeparatorChar + 'BUILD.json'
|            if ([IO.File]::Exists($bj)) {
|                $j = [IO.File]::ReadAllText($bj) | ConvertFrom-Json
|                if ("$($j.display)".Trim()) { return "$($j.display)".Trim() }
|                if ("$($j.version)".Trim()) { return "$($j.version)".Trim() }
|            }
|        } catch { }
|        try {
|            $vf = [IO.Path]::Combine($SolutionRoot, 'VERSION')
|            if ([IO.File]::Exists($vf)) { $v = ([IO.File]::ReadAllText($vf)).Trim(); if ($v) { return $v } }
|        } catch { }
|    }
|    'unknown (not a released copy)'
|}
|
|function Get-SIScriptFirstLine {
|    <# PURE. The first line of every person-run script: "<Script> version <v> - documentation: <link>". #>
|    param([Parameter(Mandatory)][string]$Script, [Parameter(Mandatory)][string]$Version)
|    $n = [IO.Path]::GetFileNameWithoutExtension($Script.Trim())
|    '{0} version {1} - documentation: {2}' -f $n, $Version, (Get-SIScriptDocUrl -Script $n)
|}
|
|function Get-SIScriptDocUrl {
|    <# PURE. The documentation page of a script (no .ps1, trailing slash -- confirmed by Invardia 2026-10-09). #>
|    param([Parameter(Mandatory)][string]$Script)
|    $n = ([IO.Path]::GetFileNameWithoutExtension($Script.Trim()))
|    'https://invardia.com/docs/si/scripts/{0}/' -f $n
|}
|
|function Get-SIScriptLogFolder {
|    <# PURE apart from reading the environment. The one known folder every script's transcript goes to. #>
|    if ($env:SI_SCRIPT_LOG_DIR) { return [string]$env:SI_SCRIPT_LOG_DIR }
|    if ($env:LOCALAPPDATA) { return [IO.Path]::Combine($env:LOCALAPPDATA, 'SecurityInsight', 'script-logs') }
|    $h = $HOME; if (-not $h) { $h = [Environment]::GetFolderPath('UserProfile') }
|    [IO.Path]::Combine($h, '.securityinsight', 'script-logs')
|}
|
|function Start-SIScriptRun {
|    <#
|        The first thing a script does. Returns the run (pass it to Stop-SIScriptRun). -WhatIf comes from the caller's
|        $WhatIfPreference; -Quiet (tests) prints nothing and starts no transcript.
|    #>
|    param([Parameter(Mandatory)][string]$Script, [switch]$Quiet, [bool]$WhatIfOn = [bool]$WhatIfPreference)
|    if ($env:SI_SCRIPT_RUN_QUIET -eq '1') { $Quiet = [switch]$true }      # tests: no banner, no transcript
|    $name = [IO.Path]::GetFileNameWithoutExtension($Script.Trim())
|    $ver = Get-SIScriptVersion
|    $run = [pscustomobject]@{ Script = $name; DocUrl = (Get-SIScriptDocUrl -Script $name); Version = $ver; FirstLine = (Get-SIScriptFirstLine -Script $name -Version $ver)
|                              Transcript = ''; Started = $false; WhatIf = $WhatIfOn; Quiet = [bool]$Quiet }
|    if ($Quiet) { return $run }
|    # the transcript FIRST (silently), so the version line below is the first line of the console AND of the transcript
|    $noTranscript = ''
|    try {
|        $dir = Get-SIScriptLogFolder
|        if (-not [IO.Directory]::Exists($dir)) { [void][IO.Directory]::CreateDirectory($dir) }
|        $path = [IO.Path]::Combine($dir, ('{0}-{1:yyyyMMdd-HHmmss}.log' -f $name, [datetime]::Now))
|        $null = Start-Transcript -LiteralPath $path -WhatIf:$false -ErrorAction Stop
|        $run.Transcript = $path; $run.Started = $true
|    } catch {
|        $noTranscript = $_.Exception.Message
|    }
|    Write-Host $run.FirstLine
|    if ($noTranscript) { Write-Host ('(no transcript of this run: {0})' -f $noTranscript) -ForegroundColor DarkGray }
|    if ($WhatIfOn) { Write-Host '-WhatIf: this run only reads and shows what it would change -- nothing is changed.' -ForegroundColor Yellow }
|    $run
|}
|
|function Stop-SIScriptRun {
|    <# The last thing a script does (in its finally block): ends the transcript and prints where it is. #>
|    param($Run)
|    if ($null -eq $Run -or $Run.Quiet) { return }
|    if ($Run.Started) {
|        try { $null = Stop-Transcript -ErrorAction Stop } catch { }
|        Write-Host ('Transcript of this run: {0}' -f $Run.Transcript)
|    }
|}
'@ }
$__siSupportFiles['setup/_shared/SI-SetupAzure.ps1'] = @{ Sha256 = 'c54979b69ba2b3fabde3641cf7fb820bf6ed4e956a2acc43d2c0c5d980144200'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight SETUP -- Azure with NO PowerShell modules: native REST, ARM and .NET only.
|
|    Dot-source this ONE file at the top of a setup script (setup\, setup\ConfigWizard\backend\, Bootstrap-*, Setup-*):
|
|        . (Join-Path $PSScriptRoot 'setup\_shared\SI-SetupAzure.ps1')      # from the solution root
|        . (Join-Path $PSScriptRoot '_shared\SI-SetupAzure.ps1')            # from setup\
|        Connect-SISetupAzure -TenantId $tid -SubscriptionId $sub           # a person, or an app (see below)
|
|    It loads the engine's REST layer (engine/_shared/SI-AzRest.ps1: Invoke-SIArm, Resource Graph, Key Vault secrets,
|    storage data plane, the *-SIAz* REST twins), switches this process to REST (SI_AzureAccess_Engine = 'Rest'), adds the
|    sign-in of a PERSON (SI-SetupSignIn.ps1: Azure Cloud Shell token endpoint, or the browser with code + PKCE), and adds
|    what setup needs that the engines never did: Key Vault vaults and certificates, resource providers, deleting a role
|    assignment, typed ARM reads (resources, VMs, managed identities, SQL, Azure OpenAI, tenants, Log Analytics tables)
|    and storage management (tables, containers and queues through ARM, the lifecycle policy, name availability --
|    never an account key).
|
|    Every call goes through Invoke-SIAzRestHttp (the engine's one HTTP seam), so the offline tests run it against a fake.
|
|    INSIDE AN INVARDIA SUPPORT SESSION (owner 2026-10-12) setup signs in to NOTHING itself: Connect-SISetupAzure and
|    Get-SISetupAzureContext answer from the session (engine/_shared/SI-AzRest.ps1, Get-SISupportSession -- the one place
|    that detects it), and every call goes through the session's recording command, so each change is in the
|    environment's audit log. A subscription the session does not name is refused.
|    PS 5.1 safe; pwsh 7 on Windows, Linux (Azure Cloud Shell) and macOS.
|#>
|
|# NO Set-StrictMode here -- it leaks into the caller's scope.
|
|$__siSetupAzureRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
|. ([IO.Path]::Combine($__siSetupAzureRoot, 'engine', '_shared', 'SI-AzRest.ps1'))
|. ([IO.Path]::Combine($__siSetupAzureRoot, 'engine', '_shared', 'SI-LogIngest.ps1'))
|. ([IO.Path]::Combine($__siSetupAzureRoot, 'auth', 'Find-SICertificate.ps1'))
|. ([IO.Path]::Combine($__siSetupAzureRoot, 'auth', 'SI-ManagedIdentity.ps1'))
|. ([IO.Path]::Combine($PSScriptRoot, 'SI-SetupSignIn.ps1'))
|Remove-Variable -Name __siSetupAzureRoot -ErrorAction SilentlyContinue
|
|# Setup never loads an Az module: every *-SIAz* wrapper takes its REST twin, and log ingestion its REST path.
|$global:SI_AzureAccess_Engine = 'Rest'
|$global:SI_LogIngest_Engine   = 'Rest'
|
|function Get-SIAzureToken {
|    <#
|        THE token function of the REST layer, as setup needs it: a signed-in PERSON (Connect-SISetupUser) is answered
|        from the setup sign-in; an app or a managed identity exactly as engine/_shared/SI-AzRest.ps1 does. Defined here,
|        after that file, so every REST helper -- Invoke-SIArm, the *-SIAz* twins, Key Vault, storage, Graph -- runs as
|        whoever signed in.
|    #>
|    param(
|        [ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience = 'Arm',
|        [string]$Resource,
|        [hashtable]$Auth,
|        [switch]$ForceRefresh
|    )
|    if (-not $Resource) { $Resource = Get-SIAzureAudience -Audience $Audience }
|    if (-not $Auth) {
|        # an Invardia Support session in the shell is setup's sign-in (never a person's or an app's beside it)
|        $null = Sync-SISupportConnection -TakeOver
|        $st = Get-SIAzRestState
|        if ($st.Connection -is [hashtable] -and $st.Connection.Mode -eq 'User') { $Auth = $st.Connection }
|    }
|    if ($Auth -and $Auth.Mode -eq 'User') { return (Get-SISetupUserToken -Resource $Resource -ForceRefresh:$ForceRefresh) }
|    # the engine's own hook ($global:SI_TokenProvider), exactly as engine/_shared/SI-AzRest.ps1 consults it
|    if (-not $Auth) {
|        $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|        if ($tp -is [scriptblock]) { $pt = [string](& $tp $Resource); if (-not [string]::IsNullOrWhiteSpace($pt)) { return $pt } }
|    }
|    Initialize-SIAzRestHelpers
|    if (-not $Auth) { $Auth = Resolve-SIAzRestAuth }
|    return (Get-SILogIngestToken -Resource $Resource -Auth $Auth -ForceRefresh:$ForceRefresh)
|}
|# published globally too: a child script that loads only the engine file still finds the setup sign-in
|Set-Item -Path 'function:global:Get-SIAzureToken' -Value ${function:Get-SIAzureToken}
|
|# =====================================================================================================================
|#  Sign-in: one entry point for a person, an app or a managed identity
|# =====================================================================================================================
|
|function Connect-SISetupAzure {
|    <#
|        Signs this PowerShell process in to Azure for setup. No module, no Connect-AzAccount.
|          -ApplicationId + -CertificateThumbprint   an app with a certificate (LocalMachine\My or CurrentUser\My)
|          -ApplicationId + -ClientSecret            an app with a client secret (string or SecureString)
|          -Identity [-ManagedIdentityClientId]      this host's managed identity
|          (none of these)                           a PERSON: Azure Cloud Shell, else the browser (-UserSignIn)
|        AN INVARDIA SUPPORT SESSION open in this shell IS the sign-in: nothing is signed in here (no browser, no
|        certificate, no token request) -- the context is the session's: its tenant, and -SubscriptionId when the session
|        names it, else its first subscription. A subscription or tenant the session does not name is refused, and so is
|        -ApplicationId / -Identity (a sign-in beside the session would not be recorded there). One plain line says so.
|        ONE connect path (#524): an existing Azure session of this process (Connect-AzAccount, az login) is never used.
|        An existing sign-in in this process is REUSED (same tenant) unless -Force. -SubscriptionId selects the
|        subscription every following call works in. The app/identity is proven by asking for an ARM token at once, so a
|        wrong secret or certificate fails here, not three steps later. Returns Get-SISetupAzureContext.
|    #>
|    [CmdletBinding()]
|    param(
|        [string]$TenantId,
|        [string]$SubscriptionId,
|        [string]$ApplicationId,
|        [string]$CertificateThumbprint,
|        $ClientSecret,
|        [switch]$Identity,
|        [string]$ManagedIdentityClientId,
|        [ValidateSet('Auto', 'CloudShell', 'Browser')][string]$UserSignIn = 'Auto',
|        [string]$LoginHint,
|        [int]$TimeoutSec = 300,
|        [switch]$Force
|    )
|    $st = Get-SIAzRestState
|    $app = ($ApplicationId -and ($CertificateThumbprint -or $ClientSecret))
|    $sess = Get-SISupportSession
|    if ($sess) {
|        $name = Get-SISupportSessionName $sess
|        if ($app -or $Identity) {
|            $who = if ($Identity) { 'a managed identity' } else { 'the app {0}' -f $ApplicationId }
|            throw ('An Invardia Support session for {0} is open in this PowerShell session: SecurityInsight setup works through it, so every change is recorded there. Signing in here as {1} would not be recorded -- refused. Run the same command without the sign-in parameters, or end the session first (Disconnect-InvardiaSupport).' -f $name, $who)
|        }
|        if ($TenantId -and $TenantId -ne $sess.TenantId) {
|            throw ('The Invardia Support session for {0} is for tenant {1}, not {2} -- refused. Connect the support session of tenant {2}.' -f $name, $sess.TenantId, $TenantId)
|        }
|        if ($SubscriptionId) { Assert-SISupportSubscription -SubscriptionId $SubscriptionId -Session $sess }
|        if (Test-SISetupUserSignedIn) { Disconnect-SISetupUser }
|        return (Get-SISetupAzureContext -SubscriptionId $SubscriptionId)
|    }
|    $null = Sync-SISupportConnection   # a Support sign-in whose session was closed is dropped
|    $existing = $st.Connection
|    $reuse = (-not $Force) -and ($existing -is [hashtable]) -and (-not $app) -and (-not $Identity) -and
|             ((-not $TenantId) -or ([string]$existing.TenantId -eq $TenantId) -or ($existing.Mode -eq 'ManagedIdentity'))
|    # 2026-11-03 (a customer install, a second run in one window): a person's connection left by an earlier run whose sign-in this run does
|    # not hold is NEVER reused -- the person is signed in again (else Get-SISetupAzureContext answers $null and the install
|    # stops "not signed in")
|    if ($reuse -and [string]$existing.Mode -eq 'User' -and -not $existing['IsApp'] -and -not (Test-SISetupUserSignedIn)) { $reuse = $false; $st.Connection = $null }
|    if (-not $reuse) {
|        if ($app -or $Identity) {
|            if (Test-SISetupUserSignedIn) { Disconnect-SISetupUser }
|            $c = @{}
|            if ($Identity) {
|                $c['Identity'] = $true
|                if ($ManagedIdentityClientId) { $c['AccountId'] = $ManagedIdentityClientId }
|            } elseif ($CertificateThumbprint) {
|                $c['ServicePrincipal'] = $true; $c['ApplicationId'] = $ApplicationId; $c['CertificateThumbprint'] = $CertificateThumbprint; $c['Tenant'] = $TenantId
|            } else {
|                $sec = if ($ClientSecret -is [System.Security.SecureString]) { $ClientSecret } else { ConvertTo-SISecureString -Text ([string]$ClientSecret) }
|                $c['ServicePrincipal'] = $true; $c['Credential'] = New-Object System.Management.Automation.PSCredential($ApplicationId, $sec); $c['Tenant'] = $TenantId
|            }
|            if ($SubscriptionId) { $c['Subscription'] = $SubscriptionId }
|            $null = Connect-SIAzAccountRest @c
|            if ($global:SI_LogIngestRunCache -is [hashtable]) { $global:SI_LogIngestRunCache.Tokens = @{} }
|            try { $null = Get-SIAzureToken -Audience Arm -ForceRefresh }
|            catch {
|                $st.Connection = $null
|                $who = if ($Identity) { 'the managed identity of this host' } else { 'app {0}' -f $ApplicationId }
|                throw ('Signing in to Azure as {0} failed: {1}' -f $who, $_.Exception.Message)
|            }
|        } elseif ([string](Get-Variable -Scope Global -Name SI_AuthMethod -ValueOnly -ErrorAction Ignore) -eq 'AzContext') {
|            # #524: the retired sign-in mode "AzContext" (borrow this process's Azure session) is refused -- never a silent fallback
|            throw ('SI_AuthMethod = AzContext (use the current Azure session of this PowerShell process) is no longer supported: setup signs in itself -- a person (Azure Cloud Shell or the browser), or an app with -ApplicationId and -CertificateThumbprint or -ClientSecret, or -Identity. Supported sign-ins: {0}.' -f (Get-SISupportedSignInText))
|        } else {
|            $u = Connect-SISetupUser -TenantId $TenantId -Method $UserSignIn -LoginHint $LoginHint -TimeoutSec $TimeoutSec
|            # #876: a sign-in handed over by the installation page may be an APPLICATION's (IsApp): it is then a service
|            # principal for every check that asks who installs -- its object id is the service principal's
|            $isApp = [bool]($u.PSObject.Properties['IsApp'] -and $u.IsApp)
|            $st.Connection = @{ Mode = 'User'; AppId = $u.Account; TenantId = $u.TenantId; ObjectId = $u.ObjectId; Method = $u.Method; IsApp = $isApp }
|            $st.TenantId = $u.TenantId
|            $st.SubscriptionId = $null
|            $st.Cache = @{}
|        }
|    }
|    if ($SubscriptionId) { $st.SubscriptionId = $SubscriptionId }
|    return (Get-SISetupAzureContext)
|}
|
|function ConvertTo-SISecureString {
|    param([string]$Text)
|    $s = New-Object System.Security.SecureString
|    foreach ($ch in ([string]$Text).ToCharArray()) { $s.AppendChar($ch) }
|    $s.MakeReadOnly()
|    return $s
|}
|
|function Get-SISetupAzureContext {
|    <#
|        Who this process is signed in as -- the shape setup read from Get-AzContext: Account.Id / .Type ('User',
|        'ServicePrincipal', 'ManagedService'), Account.ObjectId, Tenant.Id, Subscription.Id / .Name, SignInMethod.
|        $null when nobody is signed in.
|        In an Invardia Support session the context IS the session's (SignInMethod 'Support', read from the session -- no
|        sign-in and no token request): its tenant, and -SubscriptionId when the session names it, else the install's
|        configured subscription, else the session's first. THROWS only what a Support session refuses: a subscription it
|        does not name, another tenant than the configured one, a session without its recording command.
|        -SubscriptionId selects the subscription the following calls work in (as Connect-SISetupAzure -SubscriptionId).
|    #>
|    param([string]$SubscriptionId)
|    $st = Get-SIAzRestState
|    $sess = Sync-SISupportConnection -TakeOver
|    $c = $st.Connection
|    if (-not ($c -is [hashtable])) {
|        # an app configured through the SI_SPN_* globals counts as signed in (the engines' own rule)
|        try { $c = Resolve-SIAzRestAuth } catch { return $null }
|    }
|    # 2026-11-03 (an install run twice in ONE PowerShell window, the second from a newer package): a person's connection left
|    # by the earlier run while this run holds no sign-in of that person (its tokens live with the earlier run) is NOT a
|    # sign-in -- $null, so the install signs the person in again instead of failing at its first Azure call
|    if (-not $sess -and [string]$c.Mode -eq 'User' -and -not $c['IsApp'] -and (Get-Command -Name Test-SISetupUserSignedIn -ErrorAction SilentlyContinue) -and -not (Test-SISetupUserSignedIn)) { return $null }
|    if ($SubscriptionId) {
|        if ($sess) { Assert-SISupportSubscription -SubscriptionId $SubscriptionId -Session $sess }
|        $st.SubscriptionId = $SubscriptionId
|    }
|    $type = switch ([string]$c.Mode) { 'User' { $(if ($c['IsApp']) { 'ServicePrincipal' } else { 'User' }) } 'ManagedIdentity' { 'ManagedService' } default { 'ServicePrincipal' } }
|    $id = switch ([string]$c.Mode) { 'ManagedIdentity' { $(if ($c.ClientId) { [string]$c.ClientId } else { 'MSI' }) } default { [string]$c.AppId } }
|    $tid = [string]$st.TenantId
|    if (-not $tid) { $tid = [string]$c.TenantId }
|    if (-not $tid -and $c.Mode -ne 'User') { try { $tid = Get-SIAzRestTenantId } catch { } }
|    $sub = $null
|    try { $sub = Get-SIAzRestSubscriptionId } catch { }
|    if ($sess -and $sub) {
|        Assert-SISupportSubscription -SubscriptionId $sub -Session $sess
|        # the session already knows its first subscription's name: no call for it
|        if ($sess.SubscriptionName -and ([string]$sub).Trim().ToLowerInvariant() -eq $sess.SubscriptionId -and -not $st.Cache.ContainsKey('subname|' + $sub)) { $st.Cache['subname|' + $sub] = [string]$sess.SubscriptionName }
|    }
|    $subName = $sub
|    if ($sub) {
|        $k = 'subname|' + $sub
|        if ($st.Cache.ContainsKey($k)) { $subName = $st.Cache[$k] }
|        else {
|            try { $s = Invoke-SIArm -Path ('/subscriptions/' + $sub) -ApiVersion '2022-12-01' -AllowNotFound; if ($s -and $s.displayName) { $subName = [string]$s.displayName } } catch { }
|            $st.Cache[$k] = $subName
|        }
|    }
|    return [pscustomobject]@{
|        PSTypeName   = 'SI.Setup.AzureContext'
|        Name         = ('{0} ({1})' -f $subName, $id)
|        Account      = [pscustomobject]@{ Id = $id; Type = $type; ObjectId = $(if ($c.ObjectId) { [string]$c.ObjectId } else { $null }) }
|        Tenant       = [pscustomobject]@{ Id = $tid; TenantId = $tid }
|        Subscription = $(if ($sub) { [pscustomobject]@{ Id = $sub; SubscriptionId = $sub; Name = $subName; TenantId = $tid } } else { $null })
|        SignInMethod = $(if ($c.Mode -eq 'User') { [string]$c.Method } else { [string]$c.Mode })
|    }
|}
|
|function Disconnect-SISetupAzure {
|    Disconnect-SISetupUser
|    Disconnect-SIAzAccountRest
|}
|
|function Get-SISetupSignedInObjectId {
|    <# The object id of whoever is signed in: the person (from their token), else the app's service principal. #>
|    $st = Get-SIAzRestState
|    $c = $st.Connection
|    if ($c -is [hashtable] -and $c.ObjectId) { return [string]$c.ObjectId }
|    try {
|        $claims = ConvertFrom-SIJwtPayload (Get-SIAzureToken -Audience Arm)
|        if ($claims -and $claims.oid) { return [string]$claims.oid }
|    } catch { }
|    return $null
|}
|
|# =====================================================================================================================
|#  Small ARM helpers
|# =====================================================================================================================
|
|function Get-SISetupSubscriptionId {
|    param([string]$SubscriptionId)
|    if ($SubscriptionId) { return $SubscriptionId }
|    $s = Get-SIAzRestSubscriptionId
|    if (-not $s) { throw 'No Azure subscription is selected. Pass the subscription id (or sign in with access to one) and run the same command again.' }
|    return $s
|}
|
|function Get-SIArmResourceGroupFromId {
|    param([string]$Id)
|    if ([string]$Id -match '/resourceGroups/([^/]+)/') { return $Matches[1] }
|    return $null
|}
|
|# =====================================================================================================================
|#  (2) Key Vault: vaults (ARM) and certificates (data plane)
|# =====================================================================================================================
|
|function ConvertTo-SIKeyVaultObject {
|    param($V)
|    [pscustomobject]@{
|        VaultName                 = [string]$V.name
|        ResourceId                = [string]$V.id
|        ResourceGroupName         = (Get-SIArmResourceGroupFromId $V.id)
|        Location                  = [string]$V.location
|        VaultUri                  = [string]$V.properties.vaultUri
|        TenantId                  = [string]$V.properties.tenantId
|        Sku                       = [string]$V.properties.sku.name
|        EnableRbacAuthorization   = [bool]$V.properties.enableRbacAuthorization
|        EnableSoftDelete          = [bool]$V.properties.enableSoftDelete
|        EnablePurgeProtection     = [bool]$V.properties.enablePurgeProtection
|        PublicNetworkAccess       = [string]$V.properties.publicNetworkAccess
|        ProvisioningState         = [string]$V.properties.provisioningState
|        Tags                      = $V.tags
|    }
|}
|
|function Get-SIKeyVault {
|    <#
|        A Key Vault by name, the way Get-AzKeyVault found it: in -ResourceGroupName, else anywhere in the subscription.
|        -InRemovedState -Location: the soft-deleted vault of that name (DeletionDate, ScheduledPurgeDate). Not found is a
|        non-terminating error (so -ErrorAction SilentlyContinue gives $null), as for the cmdlet.
|    #>
|    [CmdletBinding()]
|    param([Alias('Name')][string]$VaultName, [string]$ResourceGroupName, [switch]$InRemovedState, [string]$Location, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    if ($InRemovedState) {
|        if (-not $Location) { throw 'Get-SIKeyVault -InRemovedState needs -Location.' }
|        $d = Invoke-SIArm -Path ("/subscriptions/$sub/providers/Microsoft.KeyVault/locations/$Location/deletedVaults/$VaultName") -ApiVersion '2023-07-01' -AllowNotFound
|        if (-not $d) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("No deleted Key Vault '{0}' in {1}." -f $VaultName, $Location) -Target $VaultName; return }
|        return [pscustomobject]@{
|            VaultName = [string]$d.name; Id = [string]$d.id; Location = [string]$d.properties.location; ResourceId = [string]$d.properties.vaultId
|            DeletionDate = $d.properties.deletionDate; ScheduledPurgeDate = $d.properties.scheduledPurgeDate; EnablePurgeProtection = [bool]$d.properties.purgeProtectionEnabled
|        }
|    }
|    if ($VaultName -and $ResourceGroupName) {
|        $v = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults/$VaultName") -ApiVersion '2023-07-01' -AllowNotFound
|        if (-not $v) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The Key Vault '{0}' was not found in resource group '{1}'." -f $VaultName, $ResourceGroupName) -Target $VaultName; return }
|        return (ConvertTo-SIKeyVaultObject $v)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults" } else { "/subscriptions/$sub/providers/Microsoft.KeyVault/vaults" }
|    $found = $false
|    foreach ($v in @(Invoke-SIArm -Path $path -ApiVersion '2023-07-01' -List)) {
|        if ($VaultName -and [string]$v.name -ne $VaultName) { continue }
|        $found = $true
|        ConvertTo-SIKeyVaultObject $v
|    }
|    if ($VaultName -and -not $found) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The Key Vault '{0}' was not found in subscription {1}." -f $VaultName, $sub) -Target $VaultName }
|}
|
|function New-SIKeyVault {
|    <# Creates (PUT) a Key Vault: soft delete on, Azure RBAC authorization by default, and waits until it is ready. #>
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][Alias('Name')][string]$VaultName,
|        [Parameter(Mandatory)][string]$ResourceGroupName,
|        [Parameter(Mandatory)][string]$Location,
|        [ValidateSet('standard', 'premium', 'Standard', 'Premium')][string]$Sku = 'standard',
|        [bool]$EnableRbacAuthorization = $true,
|        [switch]$EnablePurgeProtection,
|        [int]$SoftDeleteRetentionInDays = 90,
|        [hashtable]$Tag,
|        [string]$SubscriptionId,
|        [string]$TenantId,
|        # #866 (a private install; owner: "we will not allow fw option or exceptions"): 'Disabled' CREATES the vault with no
|        # public access at all (its firewall Deny, trusted Microsoft services allowed) -- a policy that refuses a public
|        # vault never sees one. Empty: Azure's default, as before.
|        [ValidateSet('', 'Disabled')][string]$PublicNetworkAccess = ''
|    )
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    if (-not $TenantId) { $TenantId = Get-SIAzRestTenantId }
|    $props = [ordered]@{
|        tenantId                  = $TenantId
|        sku                       = @{ family = 'A'; name = $Sku.ToLowerInvariant() }
|        enableRbacAuthorization   = $EnableRbacAuthorization
|        enableSoftDelete          = $true
|        softDeleteRetentionInDays = $SoftDeleteRetentionInDays
|        accessPolicies            = @()
|    }
|    if ($EnablePurgeProtection) { $props['enablePurgeProtection'] = $true }
|    if ($PublicNetworkAccess -eq 'Disabled') {
|        $props['publicNetworkAccess'] = 'Disabled'
|        $props['networkAcls'] = [ordered]@{ defaultAction = 'Deny'; bypass = 'AzureServices'; ipRules = @(); virtualNetworkRules = @() }
|    }
|    $body = [ordered]@{ location = $Location; properties = $props }
|    if ($Tag) { $body['tags'] = $Tag }
|    $path = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults/$VaultName"
|    $v = Invoke-SIArm -Method PUT -Path $path -ApiVersion '2023-07-01' -Body $body
|    for ($i = 0; $i -lt 30 -and $v -and [string]$v.properties.provisioningState -and [string]$v.properties.provisioningState -notin 'Succeeded', 'Failed'; $i++) {
|        Start-Sleep -Seconds 5
|        $v = Invoke-SIArm -Path $path -ApiVersion '2023-07-01' -AllowNotFound
|    }
|    if (-not $v) { throw ("The Key Vault '{0}' was requested but did not appear." -f $VaultName) }
|    return (ConvertTo-SIKeyVaultObject $v)
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|#  FRAMEWORK INSTALLER RULE 11 -- the install's Key Vault network shape, set and READ BACK every run.
|#  Rule 11 (framework REQUIREMENTS, installer rules, 3 Nov): "a PRIVATE install's Key Vault: publicNetworkAccess Disabled +
|#  networkAcls { defaultAction Deny, bypass AzureServices, no ipRules, no virtualNetworkRules } ... bypass AzureServices is
|#  REQUIRED: ARM key / secret operations ... are refused with ForbiddenByConnection under bypass None ... ENFORCE IT EVERY
|#  RUN: a re-install RECOVERS a soft-deleted vault (purge protection), and a recover IGNORES networkAcls (it comes back with
|#  bypass None) - so set the vault to this shape and READ IT BACK before any key / secret step, whether the vault was made,
|#  recovered or found." Rule 11 names only the private shape; a PUBLIC install takes the one part that is not about being
|#  private -- bypass AzureServices -- and nothing else is changed (its public access and firewall stay the customer's).
|# ---------------------------------------------------------------------------------------------------------------------
|
|function Get-SIKeyVaultNetworkShape {
|    <# PURE. The network settings of a vault as ARM returns it (PSCustomObject or hashtable): PublicNetworkAccess,
|       DefaultAction, Bypass, IpRules, VirtualNetworkRules (the rule lists, empty when there are none). #>
|    param($Vault)
|    $get = { param($o, [string]$n) if ($null -eq $o) { return $null }; if ($o -is [System.Collections.IDictionary]) { if ($o.Contains($n)) { return $o[$n] }; return $null }; $p = $o.PSObject.Properties[$n]; if ($p) { $p.Value } else { $null } }
|    $props = & $get $Vault 'properties'
|    $acl = & $get $props 'networkAcls'
|    [pscustomobject]@{
|        PublicNetworkAccess = [string](& $get $props 'publicNetworkAccess')
|        DefaultAction       = [string](& $get $acl 'defaultAction')
|        Bypass              = [string](& $get $acl 'bypass')
|        IpRules             = @(@(& $get $acl 'ipRules') | Where-Object { $null -ne $_ })
|        VirtualNetworkRules = @(@(& $get $acl 'virtualNetworkRules') | Where-Object { $null -ne $_ })
|    }
|}
|
|function Get-SIKeyVaultRule11Patch {
|    <# PURE. The PATCH body that brings -Vault to the rule-11 shape -- ONLY what differs -- or $null when it has it.
|         -Private  publicNetworkAccess Disabled + networkAcls { Deny, AzureServices, no IP rules, no network rules }
|         public    a vault open to all networks (default action Allow, or no firewall at all) already lets trusted Microsoft
|                   services in: nothing to set -- Azure does not keep a bypass on a vault without a firewall, so asking for
|                   one can never read back. Only a vault whose firewall DENIES gets bypass AzureServices; its default action
|                   and rules are kept, publicNetworkAccess is not touched -- a public install never opens or closes a vault. #>
|    param($Vault, [switch]$Private)
|    $s = Get-SIKeyVaultNetworkShape -Vault $Vault
|    $p = [ordered]@{}
|    if ($Private) {
|        if ($s.PublicNetworkAccess -ne 'Disabled') { $p['publicNetworkAccess'] = 'Disabled' }
|        if ($s.DefaultAction -ne 'Deny' -or $s.Bypass -ne 'AzureServices' -or $s.IpRules.Count -or $s.VirtualNetworkRules.Count) {
|            $p['networkAcls'] = [ordered]@{ defaultAction = 'Deny'; bypass = 'AzureServices'; ipRules = @(); virtualNetworkRules = @() }
|        }
|    } elseif ($s.DefaultAction -eq 'Deny' -and $s.Bypass -ne 'AzureServices') {
|        $p['networkAcls'] = [ordered]@{ defaultAction = 'Deny'; bypass = 'AzureServices'
|                                        ipRules = @($s.IpRules); virtualNetworkRules = @($s.VirtualNetworkRules) }
|    }
|    if (-not $p.Count) { return $null }
|    [ordered]@{ properties = $p }
|}
|
|function Test-SIKeyVaultRule11Shape {
|    <# PURE. Does -Vault read back in the rule-11 shape (private or public, as above)? #>
|    param($Vault, [switch]$Private)
|    [bool]($Vault -and $null -eq (Get-SIKeyVaultRule11Patch -Vault $Vault -Private:$Private))
|}
|
|function Get-SIKeyVaultShapeText {
|    <# PURE. One line for the log: public access, default action, bypass, rule counts. #>
|    param($Vault)
|    $s = Get-SIKeyVaultNetworkShape -Vault $Vault
|    'publicNetworkAccess {0}, defaultAction {1}, bypass {2}, ipRules {3}, virtualNetworkRules {4}' -f $(if ($s.PublicNetworkAccess) { $s.PublicNetworkAccess } else { '(not set)' }),
|        $(if ($s.DefaultAction) { $s.DefaultAction } else { '(not set)' }), $(if ($s.Bypass) { $s.Bypass } else { '(not set)' }), $s.IpRules.Count, $s.VirtualNetworkRules.Count
|}
|
|function Set-SIKeyVaultRule11 {
|    <# Sets the vault to the rule-11 shape (PATCH, only what differs) and READS IT BACK. Throws plainly when it does not read
|       back in that shape -- nothing writes a key or secret to it before it does. Returns Changed, Shape (the read-back line),
|       Vault (the read-back vault as Get-SIKeyVault returns it). #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$ResourceGroupName, [string]$SubscriptionId,
|          [switch]$Private, [int]$Tries = 12, [int]$PauseSeconds = 5)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $path = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults/$VaultName"
|    $have = Invoke-SIArm -Path $path -ApiVersion '2023-07-01' -AllowNotFound
|    if (-not $have) { throw ("The Key Vault '{0}' was not found in resource group '{1}' -- its network shape (framework installer rule 11) cannot be set." -f $VaultName, $ResourceGroupName) }
|    $patch = Get-SIKeyVaultRule11Patch -Vault $have -Private:$Private
|    $back = $have
|    if ($patch) {
|        $null = Invoke-SIArm -Method PATCH -Path $path -ApiVersion '2023-07-01' -Body $patch
|        for ($i = 1; $i -le $Tries; $i++) {
|            $back = Invoke-SIArm -Path $path -ApiVersion '2023-07-01' -AllowNotFound
|            if (Test-SIKeyVaultRule11Shape -Vault $back -Private:$Private) { break }
|            if ($i -lt $Tries) { Start-Sleep -Seconds $PauseSeconds }
|        }
|    }
|    if (-not (Test-SIKeyVaultRule11Shape -Vault $back -Private:$Private)) {
|        # Framework rule 17: the advice names ONLY the one setting that is missing -- never "set the networking", which on
|        # a public install invites "selected networks" and locks the jobs out of their own vault.
|        throw ("The Key Vault '{0}' does not read back in the shape it must have ({1}); it reads: {2}. Nothing writes a key or secret to it until it does -- run the same command again; if it stays like this, {3}, change nothing else there, and run again." -f $VaultName,
|            $(if ($Private) { 'public access Disabled, firewall Deny, trusted Microsoft services allowed (bypass AzureServices), no IP or network rules' } else { 'trusted Microsoft services allowed (bypass AzureServices)' }), (Get-SIKeyVaultShapeText -Vault $back),
|            $(if ($Private) { "in the Azure portal (Key vaults > $VaultName > Networking) choose 'Disable public access' and tick 'Allow trusted Microsoft services to bypass this firewall'" } else { "in the Azure portal (Key vaults > $VaultName > Networking > Exceptions) tick only 'Allow trusted Microsoft services to bypass this firewall'" }))
|    }
|    [pscustomobject]@{ Changed = [bool]$patch; Shape = (Get-SIKeyVaultShapeText -Vault $back); Vault = (ConvertTo-SIKeyVaultObject $back) }
|}
|
|function Get-SIKeyVaultEnsureAction {
|    <# PURE. What the install does with its vault: 'found' (it is there), 'recover' (absent, but soft-deleted in the install's
|       location FROM THE INSTALL'S OWN resource group -- a re-install; with purge protection it can neither be purged nor
|       made again under that name), 'create' (also when the deleted vault was another resource group's: the create then
|       fails with Azure's own "exists in deleted state", as before -- another install's vault is never taken over). #>
|    param($Found, $Deleted, [string]$ResourceGroupName)
|    if ($Found) { return 'found' }
|    if ($Deleted) {
|        $rg = if ([string]$Deleted.ResourceId -match '(?i)/resourceGroups/([^/]+)/') { $Matches[1] } else { '' }
|        if (-not $rg -or -not $ResourceGroupName -or $rg -eq $ResourceGroupName) { return 'recover' }
|    }
|    'create'
|}
|
|function Get-SIKeyVaultRecoverBody {
|    <# PURE. The PUT body that RECOVERS a soft-deleted vault (properties.createMode 'recover'; Azure restores its settings --
|       but NOT its networkAcls, hence Set-SIKeyVaultRule11 right after). tenantId and sku are required by the schema. #>
|    param([Parameter(Mandatory)][string]$Location, [Parameter(Mandatory)][string]$TenantId, [string]$Sku = 'standard')
|    [ordered]@{ location = $Location; properties = [ordered]@{ tenantId = $TenantId; sku = [ordered]@{ family = 'A'; name = $Sku.ToLowerInvariant() }; createMode = 'recover' } }
|}
|
|function Restore-SIKeyVault {
|    <# RECOVERS the soft-deleted vault -Deleted (Get-SIKeyVault -InRemovedState) into the resource group it was deleted from
|       (or -ResourceGroupName when that is not known), and waits until it is ready. Returns it as Get-SIKeyVault does. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)]$Deleted, [Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$Location,
|          [string]$SubscriptionId, [string]$TenantId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    if (-not $TenantId) { $TenantId = Get-SIAzRestTenantId }
|    $rg = Get-SIArmResourceGroupFromId ([string]$Deleted.ResourceId)
|    if (-not $rg) { $rg = $ResourceGroupName }
|    $name = [string]$Deleted.VaultName
|    $path = "/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.KeyVault/vaults/$name"
|    $v = Invoke-SIArm -Method PUT -Path $path -ApiVersion '2023-07-01' -Body (Get-SIKeyVaultRecoverBody -Location $Location -TenantId $TenantId)
|    for ($i = 0; $i -lt 30 -and (-not $v -or ([string]$v.properties.provisioningState -and [string]$v.properties.provisioningState -notin 'Succeeded', 'Failed')); $i++) {
|        Start-Sleep -Seconds 5
|        $v = Invoke-SIArm -Path $path -ApiVersion '2023-07-01' -AllowNotFound
|    }
|    if (-not $v) { throw ("The soft-deleted Key Vault '{0}' was recovered but did not appear." -f $name) }
|    return (ConvertTo-SIKeyVaultObject $v)
|}
|
|function Initialize-SIKeyVault {
|    <# The install's vault, FOUND, RECOVERED or CREATED -- and in every case set to the rule-11 shape and READ BACK before
|       anything writes a key or secret to it. -PublicNetworkAccess 'Disabled' = a private install (created private from
|       birth, converged to the private shape); '' = a public one. Returns Action (found | recovered | created), Vault,
|       Changed (the shape had to be set), Shape (the read-back line), Deleted (what was recovered). #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$Location,
|          [string]$SubscriptionId, [string]$TenantId, [switch]$EnablePurgeProtection,
|          [ValidateSet('', 'Disabled')][string]$PublicNetworkAccess = '', [int]$PauseSeconds = 5)
|    $isPrivate = ($PublicNetworkAccess -eq 'Disabled')
|    $kv = Get-SIKeyVault -VaultName $VaultName -SubscriptionId $SubscriptionId -ErrorAction SilentlyContinue
|    $deleted = $null
|    if (-not $kv) { $deleted = Get-SIKeyVault -VaultName $VaultName -InRemovedState -Location $Location -SubscriptionId $SubscriptionId -ErrorAction SilentlyContinue }
|    $action = Get-SIKeyVaultEnsureAction -Found $kv -Deleted $deleted -ResourceGroupName $ResourceGroupName
|    switch ($action) {
|        'create' {
|            # Azure RBAC authorization (not access policies); a private install is private from birth (no public moment)
|            $kv = New-SIKeyVault -VaultName $VaultName -ResourceGroupName $ResourceGroupName -Location $Location -SubscriptionId $SubscriptionId -TenantId $TenantId -EnableRbacAuthorization $true -EnablePurgeProtection:$EnablePurgeProtection -PublicNetworkAccess $PublicNetworkAccess
|            $action = 'created'
|        }
|        'recover' { $kv = Restore-SIKeyVault -Deleted $deleted -ResourceGroupName $ResourceGroupName -Location $Location -SubscriptionId $SubscriptionId -TenantId $TenantId; $action = 'recovered' }
|    }
|    $rg = if ([string]$kv.ResourceGroupName) { [string]$kv.ResourceGroupName } else { $ResourceGroupName }
|    $c = Set-SIKeyVaultRule11 -VaultName $VaultName -ResourceGroupName $rg -SubscriptionId $SubscriptionId -Private:$isPrivate -PauseSeconds $PauseSeconds
|    # the vault's own facts (RBAC, purge protection) from the create / recover answer; its network from the read-back
|    $out = $c.Vault
|    if (-not [string]$out.VaultUri -and $kv) { $out = $kv }
|    [pscustomobject]@{ Action = $action; Vault = $out; Changed = $c.Changed; Shape = $c.Shape; Deleted = $deleted }
|}
|
|function Test-SIKeyVaultNameAvailability {
|    <# Microsoft.KeyVault checkNameAvailability: NameAvailable, Reason, Message. #>
|    param([Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $r = Invoke-SIArm -Method POST -Path ("/subscriptions/$sub/providers/Microsoft.KeyVault/checkNameAvailability") -ApiVersion '2022-07-01' -Body @{ name = $Name; type = 'Microsoft.KeyVault/vaults' }
|    return [pscustomobject]@{ NameAvailable = [bool]$r.nameAvailable; Reason = [string]$r.reason; Message = [string]$r.message }
|}
|
|function ConvertFrom-SIBase64UrlToHex {
|    param([string]$Text)
|    if (-not $Text) { return $null }
|    $p = $Text.Replace('-', '+').Replace('_', '/')
|    switch ($p.Length % 4) { 2 { $p += '==' } 3 { $p += '=' } }
|    return (([Convert]::FromBase64String($p) | ForEach-Object { $_.ToString('X2') }) -join '')
|}
|
|function ConvertTo-SIKeyVaultCertificateObject {
|    param($J, [string]$VaultName, [string]$Name)
|    $x = $null
|    if ($J.cer) { try { $x = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(,[Convert]::FromBase64String([string]$J.cer)) } catch { } }
|    $thumb = if ($x) { [string]$x.Thumbprint } else { ConvertFrom-SIBase64UrlToHex ([string]$J.x5t) }
|    $exp = $null
|    if ($J.attributes -and $J.attributes.exp) { try { $exp = [DateTimeOffset]::FromUnixTimeSeconds([long]$J.attributes.exp).UtcDateTime } catch { } }
|    [pscustomobject]@{
|        VaultName = $VaultName; Name = $Name; Id = [string]$J.id; SecretId = [string]$J.sid; KeyId = [string]$J.kid
|        Thumbprint = $thumb; Certificate = $x; Enabled = $(if ($J.attributes) { [bool]$J.attributes.enabled } else { $null }); Expires = $exp
|    }
|}
|
|function Get-SIKeyVaultCertificate {
|    <# One certificate (current version) from a vault's data plane; $null (non-terminating error) when absent. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$Name)
|    $uri = 'https://{0}.vault.azure.net/certificates/{1}?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name)
|    $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience KeyVault -AllowNotFound -What ("Key Vault certificate '{0}' in '{1}'" -f $Name, $VaultName)
|    if (-not $r) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The certificate '{0}' was not found in Key Vault '{1}'." -f $Name, $VaultName) -Target $Name; return }
|    return (ConvertTo-SIKeyVaultCertificateObject -J ($r.Content | ConvertFrom-Json) -VaultName $VaultName -Name $Name)
|}
|
|function Import-SIKeyVaultCertificate {
|    <# Imports a PFX (-FilePath or -CertificateBytes, optional -Password) into a vault as certificate -Name. #>
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][string]$VaultName,
|        [Parameter(Mandatory)][string]$Name,
|        [string]$FilePath,
|        [byte[]]$CertificateBytes,
|        $Password
|    )
|    if (-not $CertificateBytes) {
|        if (-not $FilePath) { throw 'Import-SIKeyVaultCertificate needs -FilePath or -CertificateBytes.' }
|        $CertificateBytes = [System.IO.File]::ReadAllBytes($FilePath)
|    }
|    $pw = if ($Password -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $Password).Password } else { [string]$Password }
|    $body = [ordered]@{ value = [Convert]::ToBase64String($CertificateBytes); policy = @{ secret_props = @{ contentType = 'application/x-pkcs12' } } }
|    if ($pw) { $body['pwd'] = $pw }
|    $uri = 'https://{0}.vault.azure.net/certificates/{1}/import?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name)
|    $r = Invoke-SIAzRestRequest -Method POST -Uri $uri -Audience KeyVault -Body ($body | ConvertTo-Json -Depth 5 -Compress) -What ("Importing certificate '{0}' into Key Vault '{1}'" -f $Name, $VaultName)
|    return (ConvertTo-SIKeyVaultCertificateObject -J ($r.Content | ConvertFrom-Json) -VaultName $VaultName -Name $Name)
|}
|
|# =====================================================================================================================
|#  (3) Resource providers
|# =====================================================================================================================
|
|function Get-SIResourceProvider {
|    <# A resource provider's registration in the subscription: ProviderNamespace, RegistrationState, ResourceTypes. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ProviderNamespace, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $p = Invoke-SIArm -Path ("/subscriptions/$sub/providers/$ProviderNamespace") -ApiVersion '2021-04-01' -AllowNotFound
|    if (-not $p) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The resource provider '{0}' was not found." -f $ProviderNamespace) -Target $ProviderNamespace; return }
|    return [pscustomobject]@{ ProviderNamespace = [string]$p.namespace; RegistrationState = [string]$p.registrationState; ResourceTypes = @($p.resourceTypes); Id = [string]$p.id }
|}
|
|function Get-SISetupResourceProviderList {
|    <#
|        PURE. #564: EVERY resource provider a SecurityInsight install WRITES to -- the guided install checks and registers
|        these before the first resource. Container Apps (Microsoft.App), the registry, the workspace, diagnostic settings and
|        data collection (Microsoft.Insights), the managed identities, the Key Vault, the storage account; Pro adds Azure SQL.
|        Microsoft.Network is NOT listed: SecurityInsight creates no network resource (no virtual network, private endpoint
|        or public IP; the Container Apps environment is a consumption one without a virtual network).
|    #>
|    param([switch]$Pro)
|    $l = @('Microsoft.App', 'Microsoft.OperationalInsights', 'Microsoft.Insights', 'Microsoft.ContainerRegistry', 'Microsoft.ManagedIdentity', 'Microsoft.KeyVault', 'Microsoft.Storage')
|    if ($Pro) { $l += 'Microsoft.Sql' }
|    $l
|}
|
|function Register-SIResourceProvider {
|    <# Registers a resource provider in the subscription (idempotent; Azure finishes it in the background). #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ProviderNamespace, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $p = Invoke-SIArm -Method POST -Path ("/subscriptions/$sub/providers/$ProviderNamespace/register") -ApiVersion '2021-04-01'
|    return [pscustomobject]@{ ProviderNamespace = $ProviderNamespace; RegistrationState = $(if ($p) { [string]$p.registrationState } else { 'Registering' }) }
|}
|
|function Get-SIArmApiVersion {
|    <# The newest non-preview api-version ARM offers for -ResourceType ('Microsoft.Sql/servers', 'Microsoft.Sql/servers/databases'). Cached. #>
|    param([Parameter(Mandatory)][string]$ResourceType, [string]$SubscriptionId)
|    $st = Get-SIAzRestState
|    $key = 'apiver|' + $ResourceType.ToLowerInvariant()
|    if ($st.Cache.ContainsKey($key)) { return $st.Cache[$key] }
|    $ns, $rest = $ResourceType -split '/', 2
|    $p = Get-SIResourceProvider -ProviderNamespace $ns -SubscriptionId $SubscriptionId -ErrorAction SilentlyContinue
|    $rt = @($p.ResourceTypes | Where-Object { [string]$_.resourceType -eq $rest }) | Select-Object -First 1
|    $v = @(@($rt.apiVersions) | Where-Object { $_ -and $_ -notmatch 'preview' } | Sort-Object -Descending) | Select-Object -First 1
|    if (-not $v) { $v = @(@($rt.apiVersions) | Sort-Object -Descending) | Select-Object -First 1 }
|    if (-not $v) { throw ("Azure does not offer the resource type '{0}' in this subscription." -f $ResourceType) }
|    $st.Cache[$key] = [string]$v
|    return [string]$v
|}
|
|# =====================================================================================================================
|#  (4) Role assignments: delete, and "what does this principal hold, through its groups too"
|# =====================================================================================================================
|
|function Remove-SIRoleAssignment {
|    <#
|        Deletes a role assignment: -RoleAssignmentId, or every assignment of -RoleDefinitionName to -ObjectId exactly at
|        -Scope. Returns what was removed. Absent = nothing to do (idempotent).
|    #>
|    [CmdletBinding()]
|    param([string]$RoleAssignmentId, [string]$ObjectId, [string]$RoleDefinitionName, [string]$Scope)
|    $ids = @()
|    if ($RoleAssignmentId) { $ids = @($RoleAssignmentId) }
|    else {
|        if (-not ($ObjectId -and $RoleDefinitionName -and $Scope)) { throw 'Remove-SIRoleAssignment needs -RoleAssignmentId, or -ObjectId with -RoleDefinitionName and -Scope.' }
|        $ids = @(Get-SIAzRoleAssignmentRest -ObjectId $ObjectId -Scope $Scope -RoleDefinitionName $RoleDefinitionName |
|                 Where-Object { ([string]$_.Scope).TrimEnd('/') -ieq $Scope.TrimEnd('/') } | ForEach-Object { [string]$_.RoleAssignmentId })
|    }
|    foreach ($id in $ids) {
|        $null = Invoke-SIArm -Method DELETE -Path $id -ApiVersion '2022-04-01' -AllowNotFound
|        [pscustomobject]@{ RoleAssignmentId = $id; ObjectId = $ObjectId; RoleDefinitionName = $RoleDefinitionName; Scope = $Scope }
|    }
|}
|
|function New-SIRoleAssignment {
|    <#
|        Assigns -RoleDefinitionName to -ObjectId at -Scope, with the principal's type stated (-PrincipalType, default
|        ServicePrincipal) -- what New-AzRoleAssignment -ObjectType did: ARM then accepts a principal that was created
|        seconds ago and has not replicated yet. Same output shape as New-SIAzRoleAssignment.
|    #>
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][string]$ObjectId,
|        [Parameter(Mandatory)][string]$Scope,
|        [Parameter(Mandatory)][string]$RoleDefinitionName,
|        [ValidateSet('ServicePrincipal', 'User', 'Group', 'ForeignGroup', 'Device')][string]$PrincipalType = 'ServicePrincipal'
|    )
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    $def = @(Get-SIAzRestRoleDefinitions -Scope $subScope | Where-Object { [string]$_.properties.roleName -eq $RoleDefinitionName }) | Select-Object -First 1
|    if (-not $def) { throw ("The role definition '{0}' was not found at scope '{1}'." -f $RoleDefinitionName, $subScope) }
|    $body = @{ properties = @{ roleDefinitionId = [string]$def.id; principalId = $ObjectId; principalType = $PrincipalType } }
|    $a = Invoke-SIArm -Method PUT -Path ($Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments/' + [guid]::NewGuid().ToString()) -ApiVersion '2022-04-01' -Body $body
|    return [pscustomobject]@{ RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = $Scope; RoleDefinitionName = $RoleDefinitionName; RoleDefinitionId = [string]$def.name; ObjectId = $ObjectId; ObjectType = $PrincipalType }
|}
|
|function Get-SIRoleAssignmentAssignedTo {
|    <#
|        The role assignments that apply to -ObjectId at or above -Scope, INCLUDING those it holds through a group
|        (ARM's assignedTo() filter -- what Get-AzRoleAssignment -ExpandPrincipalGroups returned). Same object shape as
|        Get-SIAzRoleAssignment.
|    #>
|    param([Parameter(Mandatory)][string]$ObjectId, [string]$Scope, [string]$RoleDefinitionName)
|    if (-not $Scope) { $Scope = '/subscriptions/' + (Get-SISetupSubscriptionId) }
|    $path = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments?$filter=' + [uri]::EscapeDataString(("assignedTo('{0}')" -f $ObjectId))
|    $items = @(Invoke-SIArm -Path $path -ApiVersion '2022-04-01' -List)
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    $defs = @{}
|    foreach ($d in @(Get-SIAzRestRoleDefinitions -Scope $subScope)) { $defs[([string]$d.name).ToLowerInvariant()] = [string]$d.properties.roleName }
|    foreach ($a in $items) {
|        $rdId = ([string]$a.properties.roleDefinitionId -split '/')[-1]
|        $rdName = $defs[$rdId.ToLowerInvariant()]
|        if ($RoleDefinitionName -and $rdName -ne $RoleDefinitionName) { continue }
|        [pscustomobject]@{
|            RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = [string]$a.properties.scope
|            RoleDefinitionName = $rdName; RoleDefinitionId = $rdId; ObjectId = [string]$a.properties.principalId; ObjectType = [string]$a.properties.principalType
|        }
|    }
|}
|
|# =====================================================================================================================
|#  (5) Typed ARM reads
|# =====================================================================================================================
|
|function Get-SIArmResource {
|    <#
|        One resource by -ResourceId (api-version given, or the newest ARM offers for its type), or every resource of
|        -ResourceType (and -Name / -ResourceGroupName) in the subscription -- what Get-AzResource did. Objects carry
|        ResourceId, Id, Name, ResourceGroupName, ResourceType, Location, Tags, Properties, Identity.
|    #>
|    [CmdletBinding()]
|    param([string]$ResourceId, [string]$ResourceType, [string]$Name, [string]$ResourceGroupName, [string]$ApiVersion, [string]$SubscriptionId)
|    $conv = {
|        param($R)
|        [pscustomobject]@{
|            ResourceId = [string]$R.id; Id = [string]$R.id; Name = [string]$R.name; ResourceGroupName = (Get-SIArmResourceGroupFromId $R.id)
|            ResourceType = [string]$R.type; Type = [string]$R.type; Location = [string]$R.location; Tags = $R.tags; Kind = [string]$R.kind
|            Sku = $R.sku; Properties = $R.properties; Identity = $R.identity
|        }
|    }
|    if ($ResourceId) {
|        if (-not $ApiVersion) {
|            $t = if ($ResourceId -match '/providers/([^/]+)/(.+)$') {
|                $segs = $Matches[2] -split '/'
|                $Matches[1] + '/' + ((0..($segs.Count - 1) | Where-Object { $_ % 2 -eq 0 } | ForEach-Object { $segs[$_] }) -join '/')
|            } else { $null }
|            if (-not $t) { throw ("Not an Azure resource id: {0}" -f $ResourceId) }
|            $ApiVersion = Get-SIArmApiVersion -ResourceType $t
|        }
|        $r = Invoke-SIArm -Path $ResourceId -ApiVersion $ApiVersion -AllowNotFound
|        if (-not $r) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The resource '{0}' was not found." -f $ResourceId) -Target $ResourceId; return }
|        return (& $conv $r)
|    }
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $f = @()
|    if ($ResourceType) { $f += ("resourceType eq '{0}'" -f $ResourceType) }
|    if ($Name) { $f += ("name eq '{0}'" -f $Name) }
|    $base = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/resources" } else { "/subscriptions/$sub/resources" }
|    if ($f.Count) { $base += '?$filter=' + [uri]::EscapeDataString(($f -join ' and ')) }
|    foreach ($r in @(Invoke-SIArm -Path $base -ApiVersion '2021-04-01' -List)) {
|        if ($Name -and [string]$r.name -ne $Name) { continue }
|        & $conv $r
|    }
|}
|
|function Get-SIVirtualMachine {
|    <# A VM: Name, Id, ResourceGroupName, Location, Identity (type, principalId, userAssignedIdentities), VmId. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $v = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Compute/virtualMachines/$Name") -ApiVersion '2023-09-01' -AllowNotFound
|    if (-not $v) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The virtual machine '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|    [pscustomobject]@{ Name = [string]$v.name; Id = [string]$v.id; ResourceGroupName = $ResourceGroupName; Location = [string]$v.location; VmId = [string]$v.properties.vmId; Identity = $v.identity; Tags = $v.tags }
|}
|
|function Get-SIUserAssignedIdentity {
|    <# A user-assigned managed identity: Name, Id, ClientId, PrincipalId, TenantId, Location. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $u = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$Name") -ApiVersion '2023-01-31' -AllowNotFound
|    if (-not $u) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The managed identity '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|    [pscustomobject]@{
|        Name = [string]$u.name; Id = [string]$u.id; ResourceGroupName = $ResourceGroupName; Location = [string]$u.location
|        ClientId = [string]$u.properties.clientId; PrincipalId = [string]$u.properties.principalId; TenantId = [string]$u.properties.tenantId
|    }
|}
|
|function New-SIUserAssignedIdentity {
|    <# Creates (or returns) a user-assigned managed identity. Idempotent: an existing one is returned unchanged. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$Name, [Parameter(Mandatory)][string]$Location,
|          [string]$SubscriptionId, [hashtable]$Tag)
|    $have = Get-SIUserAssignedIdentity -ResourceGroupName $ResourceGroupName -Name $Name -SubscriptionId $SubscriptionId -ErrorAction SilentlyContinue
|    if ($have) { return $have }
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $body = @{ location = $Location }
|    if ($Tag -and $Tag.Count) { $body.tags = $Tag }
|    $path = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$Name"
|    # The create's own answer carries the two ids; a read right after it can still say "not found", or come without them.
|    # So: the answer first, then the identity re-read (6 x 5 s) until BOTH ids are there -- and a clear stop when they
|    # never come: everything after this (role assignments, the jobs' sign-in) needs them.
|    $u = Invoke-SIArm -Method PUT -Path $path -ApiVersion '2023-01-31' -Body $body
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    for ($i = 0; $i -lt 6; $i++) {
|        if ($u -and $u.properties -and [string]$u.properties.clientId -and [string]$u.properties.principalId) { break }
|        if ($sleep -is [scriptblock]) { & $sleep 5 } else { Start-Sleep -Seconds 5 }
|        $u = Invoke-SIArm -Path $path -ApiVersion '2023-01-31' -AllowNotFound
|    }
|    if (-not $u -or -not $u.properties -or -not [string]$u.properties.clientId -or -not [string]$u.properties.principalId) {
|        throw ("The managed identity '{0}' was created in resource group '{1}', but Azure does not show its client id and principal id yet -- run the same command again in a minute." -f $Name, $ResourceGroupName)
|    }
|    [pscustomobject]@{
|        Name = [string]$u.name; Id = [string]$u.id; ResourceGroupName = $ResourceGroupName; Location = [string]$u.location
|        ClientId = [string]$u.properties.clientId; PrincipalId = [string]$u.properties.principalId; TenantId = [string]$u.properties.tenantId
|    }
|}
|
|function Get-SIVmIdentityPatchBody {
|    <#
|        PURE. The 'identity' body that ADDS a user-assigned identity to a VM and keeps every identity it already has: a
|        system-assigned identity stays (type 'SystemAssigned, UserAssigned'), other user-assigned ones stay listed.
|        Returns $null when the identity is already attached (nothing to change).
|    #>
|    param([AllowNull()]$CurrentIdentity, [Parameter(Mandatory)][string]$IdentityResourceId)
|    $type = if ($CurrentIdentity -and $CurrentIdentity.PSObject.Properties['type']) { [string]$CurrentIdentity.type } else { '' }
|    $ids = [ordered]@{}
|    if ($CurrentIdentity -and $CurrentIdentity.PSObject.Properties['userAssignedIdentities'] -and $CurrentIdentity.userAssignedIdentities) {
|        foreach ($p in $CurrentIdentity.userAssignedIdentities.PSObject.Properties) { $ids[$p.Name] = @{} }
|    }
|    if (@($ids.Keys | Where-Object { "$_" -ieq $IdentityResourceId }).Count) { return $null }
|    $ids[$IdentityResourceId] = @{}
|    $newType = if ($type -match '(?i)SystemAssigned') { 'SystemAssigned, UserAssigned' } else { 'UserAssigned' }
|    @{ identity = @{ type = $newType; userAssignedIdentities = $ids } }
|}
|
|function Add-SIVmUserAssignedIdentity {
|    <# Attaches a user-assigned identity to an Azure VM, keeping the identities it has. Returns $true when it changed. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$VmName,
|          [Parameter(Mandatory)][string]$IdentityResourceId, [string]$SubscriptionId)
|    $vm = Get-SIVirtualMachine -ResourceGroupName $ResourceGroupName -Name $VmName -SubscriptionId $SubscriptionId -ErrorAction Stop
|    $body = Get-SIVmIdentityPatchBody -CurrentIdentity $vm.Identity -IdentityResourceId $IdentityResourceId
|    if (-not $body) { return $false }
|    $null = Invoke-SIArm -Method PATCH -Path $vm.Id -ApiVersion '2023-09-01' -Body $body
|    $true
|}
|
|function Get-SISqlServer {
|    <# Azure SQL logical servers: ServerName, ResourceId, ResourceGroupName, Location, FullyQualifiedDomainName, Administrators. #>
|    [CmdletBinding()]
|    param([string]$ResourceGroupName, [string]$ServerName, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $conv = {
|        param($S)
|        [pscustomobject]@{
|            ServerName = [string]$S.name; ResourceId = [string]$S.id; ResourceGroupName = (Get-SIArmResourceGroupFromId $S.id); Location = [string]$S.location
|            FullyQualifiedDomainName = [string]$S.properties.fullyQualifiedDomainName; Administrators = $S.properties.administrators
|            PublicNetworkAccess = [string]$S.properties.publicNetworkAccess; Tags = $S.tags
|        }
|    }
|    if ($ResourceGroupName -and $ServerName) {
|        $s = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Sql/servers/$ServerName") -ApiVersion '2021-11-01' -AllowNotFound
|        if (-not $s) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The SQL server '{0}' was not found in resource group '{1}'." -f $ServerName, $ResourceGroupName) -Target $ServerName; return }
|        return (& $conv $s)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Sql/servers" } else { "/subscriptions/$sub/providers/Microsoft.Sql/servers" }
|    foreach ($s in @(Invoke-SIArm -Path $path -ApiVersion '2021-11-01' -List)) { if (-not $ServerName -or [string]$s.name -eq $ServerName) { & $conv $s } }
|}
|
|function Get-SISqlDatabase {
|    <# Databases of an Azure SQL server: DatabaseName, ResourceId, ServerName, Status, SkuName. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$ServerName, [string]$DatabaseName, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $base = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Sql/servers/$ServerName/databases"
|    $conv = { param($D) [pscustomobject]@{ DatabaseName = [string]$D.name; ResourceId = [string]$D.id; ServerName = $ServerName; ResourceGroupName = $ResourceGroupName; Location = [string]$D.location; Status = [string]$D.properties.status; SkuName = [string]$D.sku.name } }
|    if ($DatabaseName) {
|        $d = Invoke-SIArm -Path ($base + '/' + $DatabaseName) -ApiVersion '2021-11-01' -AllowNotFound
|        if (-not $d) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The database '{0}' was not found on SQL server '{1}'." -f $DatabaseName, $ServerName) -Target $DatabaseName; return }
|        return (& $conv $d)
|    }
|    foreach ($d in @(Invoke-SIArm -Path $base -ApiVersion '2021-11-01' -List)) { & $conv $d }
|}
|
|function Get-SICognitiveServicesAccount {
|    <# Azure OpenAI / Cognitive Services accounts: AccountName, Id, ResourceGroupName, Kind, Endpoint, Location. #>
|    [CmdletBinding()]
|    param([string]$ResourceGroupName, [string]$Name, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $conv = { param($A) [pscustomobject]@{ AccountName = [string]$A.name; Id = [string]$A.id; ResourceGroupName = (Get-SIArmResourceGroupFromId $A.id); Kind = [string]$A.kind; Location = [string]$A.location; Endpoint = [string]$A.properties.endpoint; Sku = [string]$A.sku.name } }
|    if ($ResourceGroupName -and $Name) {
|        $a = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.CognitiveServices/accounts/$Name") -ApiVersion '2023-05-01' -AllowNotFound
|        if (-not $a) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The Azure AI account '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (& $conv $a)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.CognitiveServices/accounts" } else { "/subscriptions/$sub/providers/Microsoft.CognitiveServices/accounts" }
|    foreach ($a in @(Invoke-SIArm -Path $path -ApiVersion '2023-05-01' -List)) { if (-not $Name -or [string]$a.name -eq $Name) { & $conv $a } }
|}
|
|function Get-SITenant {
|    <# The tenants the signed-in account can see: Id, TenantId, Name, DefaultDomain, Domains. -TenantId picks one. #>
|    [CmdletBinding()]
|    param([string]$TenantId)
|    $found = $false
|    foreach ($t in @(Invoke-SIArm -Path '/tenants' -ApiVersion '2022-12-01' -List)) {
|        if ($TenantId -and [string]$t.tenantId -ne $TenantId) { continue }
|        $found = $true
|        [pscustomobject]@{ Id = [string]$t.tenantId; TenantId = [string]$t.tenantId; Name = [string]$t.displayName; DefaultDomain = [string]$t.defaultDomain; Domains = @($t.domains); TenantCategory = [string]$t.tenantCategory }
|    }
|    if ($TenantId -and -not $found) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The tenant '{0}' is not visible to the signed-in account." -f $TenantId) -Target $TenantId }
|}
|
|function Get-SILogAnalyticsTable {
|    <# One Log Analytics table (or all): Name, Id, Plan, RetentionInDays, TotalRetentionInDays, Schema (columns). #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$WorkspaceName, [string]$TableName, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $base = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces/$WorkspaceName/tables"
|    $conv = { param($T) [pscustomobject]@{ Name = [string]$T.name; Id = [string]$T.id; Plan = [string]$T.properties.plan; RetentionInDays = $T.properties.retentionInDays; TotalRetentionInDays = $T.properties.totalRetentionInDays; Schema = $T.properties.schema; ProvisioningState = [string]$T.properties.provisioningState } }
|    if ($TableName) {
|        $t = Invoke-SIArm -Path ($base + '/' + $TableName) -ApiVersion '2022-10-01' -AllowNotFound
|        if (-not $t) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The table '{0}' was not found in workspace '{1}'." -f $TableName, $WorkspaceName) -Target $TableName; return }
|        return (& $conv $t)
|    }
|    foreach ($t in @(Invoke-SIArm -Path $base -ApiVersion '2022-10-01' -List)) { & $conv $t }
|}
|
|# =====================================================================================================================
|#  (7) Storage management through ARM (no data-plane role and no account key needed)
|# =====================================================================================================================
|
|function Get-SIStorageArmChildPath {
|    param([string]$SubscriptionId, [string]$ResourceGroupName, [string]$AccountName, [ValidateSet('Table', 'Container', 'Queue')][string]$Kind, [string]$Name)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $svc = switch ($Kind) { 'Table' { 'tableServices/default/tables' } 'Container' { 'blobServices/default/containers' } 'Queue' { 'queueServices/default/queues' } }
|    return ('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/{2}/{3}/{4}' -f $sub, $ResourceGroupName, $AccountName, $svc, $Name)
|}
|
|function Get-SIStorageArmChild {
|    <# A table / blob container / queue of a storage account, read through ARM; non-terminating not-found. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$AccountName,
|          [Parameter(Mandatory)][ValidateSet('Table', 'Container', 'Queue')][string]$Kind, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $p = Get-SIStorageArmChildPath -SubscriptionId $SubscriptionId -ResourceGroupName $ResourceGroupName -AccountName $AccountName -Kind $Kind -Name $Name
|    $r = Invoke-SIArm -Path $p -ApiVersion '2023-01-01' -AllowNotFound
|    if (-not $r) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The {0} '{1}' was not found in storage account '{2}'." -f $Kind.ToLowerInvariant(), $Name, $AccountName) -Target $Name; return }
|    return [pscustomobject]@{ Name = [string]$r.name; Id = [string]$r.id; Kind = $Kind; Properties = $r.properties }
|}
|
|function New-SIStorageArmChild {
|    <# Creates (PUT, idempotent) a table / private blob container / queue through ARM. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$AccountName,
|          [Parameter(Mandatory)][ValidateSet('Table', 'Container', 'Queue')][string]$Kind, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $p = Get-SIStorageArmChildPath -SubscriptionId $SubscriptionId -ResourceGroupName $ResourceGroupName -AccountName $AccountName -Kind $Kind -Name $Name
|    $body = if ($Kind -eq 'Container') { @{ properties = @{ publicAccess = 'None' } } } else { @{ properties = @{} } }
|    $r = Invoke-SIArm -Method PUT -Path $p -ApiVersion '2023-01-01' -Body $body
|    return [pscustomobject]@{ Name = $(if ($r) { [string]$r.name } else { $Name }); Id = $(if ($r) { [string]$r.id } else { $p }); Kind = $Kind }
|}
|
|function Get-SIStorageLifecyclePolicy {
|    <# The account's lifecycle management policy: .Rules (the raw ARM rules: name, enabled, type, definition); $null when there is none. #>
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$AccountName, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $p = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$AccountName/managementPolicies/default") -ApiVersion '2023-01-01' -AllowNotFound
|    if (-not $p) { return $null }
|    return [pscustomobject]@{ Id = [string]$p.id; Rules = @($p.properties.policy.rules | Where-Object { $_ }); LastModifiedTime = $p.properties.lastModifiedTime }
|}
|
|function Set-SIStorageLifecyclePolicy {
|    <# REPLACES the account's lifecycle policy with -Rules (raw ARM rule objects). Callers merge, see New-SIStorageLifecycleDeleteRule. #>
|    param([Parameter(Mandatory)][string]$ResourceGroupName, [Parameter(Mandatory)][string]$AccountName, [Parameter(Mandatory)][object[]]$Rules, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $p = Invoke-SIArm -Method PUT -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$AccountName/managementPolicies/default") -ApiVersion '2023-01-01' `
|             -Body @{ properties = @{ policy = @{ rules = @($Rules) } } }
|    return [pscustomobject]@{ Id = [string]$p.id; Rules = @($p.properties.policy.rules | Where-Object { $_ }) }
|}
|
|function New-SIStorageLifecycleDeleteRule {
|    <# PURE. A lifecycle rule that deletes block blobs under -PrefixMatch N days after their last modification. #>
|    param([Parameter(Mandatory)][string]$Name, [Parameter(Mandatory)][string[]]$PrefixMatch, [Parameter(Mandatory)][int]$DaysAfterModification)
|    return [ordered]@{
|        enabled    = $true
|        name       = $Name
|        type       = 'Lifecycle'
|        definition = [ordered]@{
|            actions = @{ baseBlob = @{ delete = @{ daysAfterModificationGreaterThan = $DaysAfterModification } } }
|            filters = [ordered]@{ blobTypes = @('blockBlob'); prefixMatch = @($PrefixMatch) }
|        }
|    }
|}
|
|function Get-SIStorageLifecycleRuleDeleteDays {
|    <# PURE. The delete-after-modification days of a raw lifecycle rule ($null when it has none). #>
|    param($Rule)
|    try { return $Rule.definition.actions.baseBlob.delete.daysAfterModificationGreaterThan } catch { return $null }
|}
|
|function Test-SIStorageAccountNameAvailability {
|    <# Microsoft.Storage checkNameAvailability: NameAvailable, Reason, Message. #>
|    param([Parameter(Mandatory)][string]$Name, [string]$SubscriptionId)
|    $sub = Get-SISetupSubscriptionId -SubscriptionId $SubscriptionId
|    $r = Invoke-SIArm -Method POST -Path ("/subscriptions/$sub/providers/Microsoft.Storage/checkNameAvailability") -ApiVersion '2023-01-01' -Body @{ name = $Name; type = 'Microsoft.Storage/storageAccounts' }
|    return [pscustomobject]@{ NameAvailable = [bool]$r.nameAvailable; Reason = [string]$r.reason; Message = [string]$r.message }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-AzRest.ps1'] = @{ Sha256 = 'ab77e822fccc463f44911a2b47f52d56e82bdaac4b48f605f2252ecd332bfd5f'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- Azure over plain REST, without the Az.* PowerShell modules (REQUIREMENTS 9.3, decision 2:
|    "no PS module dependencies ... go pure REST").
|
|    SecurityInsight runs with NO PowerShell modules: every Azure call is plain REST with tokens from SecurityInsight's
|    own sign-in (managed identity, certificate client assertion, client secret -- the run's decision). There is no
|    switch and no module path: no Az module is loaded, installed or needed anywhere in the runtime.
|
|    The call sites keep the familiar names with 'SIAz' in place of 'Az' (Invoke-SIAzOperationalInsightsQuery,
|    Search-SIAzGraph, ...). Each wrapper takes the arguments the call sites pass and does the job over REST (its *Rest
|    twin), returning objects with the properties the call sites read. Connect-SIAzAccount only RECORDS which identity to
|    sign in as; each REST call mints its token when it needs one.
|    The REST building blocks are public and usable directly:
|        Get-SIAzureToken -Audience Arm|LaQuery|Storage|KeyVault|Graph      one token function per audience
|        Invoke-SILaQuery                                                   Log Analytics data plane (api.loganalytics.io)
|        Invoke-SIArm                                                       ARM GET/PUT/PATCH/DELETE, list with nextLink
|        Search-SIResourceGraph                                             Resource Graph, every page ($skipToken)
|        Get-SIKeyVaultSecretValue                                          one secret, as plain text
|        Get-SIBlobContent / Set-SIBlobContent / Get-SIBlobList / ...       blob data plane (OAuth, x-ms-version)
|        Send-SIQueueMessage / Receive-SIQueueMessage / Remove-SIQueueMessage
|        Get-SITableEntity / Set-SITableEntity                              table data plane (upsert)
|
|    HTTP: every call of this file goes through Invoke-SIAzRestHttp. Token requests (client secret) go through
|    SI-LogIngest.ps1's Invoke-SILogIngestHttp -- the same HttpWebRequest shape; tests mock both seams.
|    Token hook: $global:SI_TokenProvider = { param($Resource) ... } (a scriptblock returning a bearer token) is consulted
|    first by Get-SIAzureToken and Get-SILogIngestToken when set -- for a host with its own sign-in, e.g. setup.
|
|    Retry rule (CLAUDE.md working rule 4): 429 / 408 / 5xx / no response -> wait (Retry-After when sent) and retry
|    in-run; 401 once -> refresh the token and repeat once; any other 4xx -> FAIL FAST with the service's own body.
|
|    PS 5.1 safe (no ?. / ??, no RSA.ImportFromPem); works on pwsh 7 and in a Linux container (no Cert: drive needed).
|    Ships in both editions and never references a Pro path.
|#>
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|# #730: the streaming Log Analytics reader (Invoke-SILaQuery reads Risk Analysis' answers with it; compiled on first use)
|if (-not (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore)) {
|    $__siLaStream = [System.IO.Path]::Combine($PSScriptRoot, 'SI-LaStreamRead.ps1')
|    if ([System.IO.File]::Exists($__siLaStream)) { . $__siLaStream }
|}
|
|# ONE connect path (#524, owner 2026-10-09 "modern single connect only"): SecurityInsight's own REST token client --
|# managed identity, certificate, client secret (and, in setup, a person's own sign-in). The old sign-in mode "AzContext"
|# (#413: borrow the current Azure / Invardia Support session of the process) and its file SI-AzSession.ps1 are gone.
|#
|# ONE TOKEN SOURCE more for that same path (#524, owner 2026-10-09 via Invardia: "support installs use TOKENS, never the
|# secret"): in a shell where Invardia's Connect-InvardiaSupport is open, its function Get-InvardiaSupportToken -Resource <r>
|# returns a bearer token as the customer's Invardia support app (cached by Invardia, tid + appid verified there). SI takes
|# EVERY token from it -- Mode 'Support' -- and still checks each token's tenant against the tenant it works in. No session
|# state is read (only the token), no Az / Graph cmdlet is called. Outside a support session nothing changes.
|#
|# THE SESSION ITSELF IS USED (owner 2026-10-12: a change in an environment is made inside its Invardia Support session, so
|# it is recorded in that environment's audit log). Get-SISupportSession is the ONE place that says whether a session is
|# open: Invardia's $global:InvardiaSupportState names a tenant AND its recording command Invoke-InvardiaSupportRequest is
|# in the shell. With a session, who SecurityInsight works as (tenant, app, subscriptions) is read from it -- no sign-in of
|# SecurityInsight's own and no token request -- and every HTTP call goes through the recording command (Invoke-SISupportHttp).
|
|function Get-SISupportedSignInText {
|    <# PURE. The sign-ins SecurityInsight supports, for an error message. #>
|    'a managed identity (SI_AuthMethod = ManagedIdentity), an app with a certificate (SI_SPN_AppId + SI_SPN_TenantId + SI_SPN_CertThumbprint), an app with a client secret (SI_SPN_AppId + SI_SPN_TenantId + SI_SPN_Secret), or the tokens of an Invardia support session (Get-InvardiaSupportToken). An Azure session of this PowerShell process (Connect-AzAccount, az login) is never used'
|}
|
|function Get-SISupportSession {
|    <#
|        THE ONE PLACE that says whether an Invardia Support session is open in this PowerShell session, and what it names.
|        Open = Invardia's $global:InvardiaSupportState is a hashtable that names a tenant AND its recording command
|        Invoke-InvardiaSupportRequest is here (Test-Path Function: -- never Get-Command, which can load a module).
|        $null when there is none (Disconnect-InvardiaSupport empties the state). Never guessed: a state WITHOUT the
|        recording command is said and stops the caller -- nothing could be recorded.
|        Returns TenantId, AppId, Environment (the handle), EnvironmentId, SessionId, Subscriptions (lower case; the ones the
|        environment names), SubscriptionId (the first of them, '' when it names none), SubscriptionName.
|    #>
|    $s = Get-Variable -Scope Global -Name InvardiaSupportState -ValueOnly -ErrorAction Ignore
|    if (-not ($s -is [hashtable])) { return $null }
|    $tid = [string]$s['TenantId']
|    if ([string]::IsNullOrWhiteSpace($tid)) { return $null }
|    if (-not (Test-Path -LiteralPath 'Function:\Invoke-InvardiaSupportRequest')) {
|        throw ('An Invardia Support session is noted in this PowerShell session (tenant {0}), but its recording command Invoke-InvardiaSupportRequest is not here, so nothing SecurityInsight does could be recorded. Nothing was done. Open the session again (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>''), or end it (Disconnect-InvardiaSupport) and work with your own sign-in.' -f $tid)
|    }
|    $subs = @(@($s['Subscriptions']) | Where-Object { $_ } | ForEach-Object { ([string]$_).Trim().ToLowerInvariant() } | Where-Object { $_ })
|    $first = ''
|    if ($subs.Count) { $first = [string]$subs[0] }
|    return [pscustomobject]@{
|        TenantId = $tid.Trim(); AppId = [string]$s['AppId']; Environment = [string]$s['Environment']; EnvironmentId = [string]$s['EnvironmentId']
|        SessionId = [string]$s['SessionId']; Subscriptions = [string[]]$subs; SubscriptionId = $first; SubscriptionName = [string]$s['SubscriptionName']
|    }
|}
|
|function Get-SISupportSessionName {
|    <# PURE. How a Support session is named in a message: its environment handle, else its tenant. #>
|    param($Session)
|    if ($Session -and [string]$Session.Environment) { return [string]$Session.Environment }
|    if ($Session) { return ('tenant {0}' -f $Session.TenantId) }
|    return ''
|}
|
|function Assert-SISupportSubscription {
|    <# In a Support session only a subscription the environment names is worked in: any other is REFUSED (throws). A session
|       whose environment names no subscription refuses none (Invardia's own rule). No session = nothing to check. #>
|    param([string]$SubscriptionId, $Session)
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) { return }
|    if (-not $Session) { $Session = Get-SISupportSession }
|    if (-not $Session) { return }
|    $named = @($Session.Subscriptions)
|    if ($named.Count -and $named -notcontains $SubscriptionId.Trim().ToLowerInvariant()) {
|        throw ('Subscription {0} is not one the Invardia Support session for {1} names ({2}) -- refused, nothing was done there. Use a subscription of this environment, or open the Support session of the environment that owns {0}.' -f $SubscriptionId, (Get-SISupportSessionName $Session), ($named -join ', '))
|    }
|}
|
|function Test-SISupportTokenSource {
|    <# Is an Invardia Support session open in this shell? (Get-SISupportSession decides -- the one place.) #>
|    return [bool](Get-SISupportSession)
|}
|
|function Get-SISupportExpectedTenantId {
|    <# The tenant SI works in, which the Support session must be for: -TenantId, else the configured one. Empty = the
|       session's own. #>
|    param([string]$TenantId)
|    if ($TenantId) { return $TenantId }
|    return [string](Get-SIAzRestValue 'SI_SPN_TenantId', 'SpnTenantId', 'AzureTenantId', 'TenantId')
|}
|
|function Get-SISupportToken {
|    <#
|        A bearer token for -Resource from the Invardia Support session; its 'tid' must be -TenantId (refused otherwise).
|        ONLY for what has no HTTP request the recording command can send -- the SQL sign-in of a database step, the
|        container registry's own token exchange, reading who the Support app is from its token. Invardia records that the
|        token was issued; what is done with it is not recorded. Every HTTP call goes through Invoke-SISupportHttp instead
|        and asks for no token here.
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [string]$TenantId, [switch]$ForceRefresh)
|    if (-not (Get-SISupportSession)) { throw 'No Invardia Support session is open in this PowerShell session (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>'').' }
|    if (-not (Test-Path -LiteralPath 'Function:\Get-InvardiaSupportToken')) { throw ('The Invardia Support session in this PowerShell session has no token command (Get-InvardiaSupportToken), so no token for {0} can be taken from it. Open the session again (Connect-InvardiaSupport).' -f $Resource) }
|    $p = @{ Resource = $Resource.TrimEnd('/') }
|    if ($ForceRefresh) { $p['ForceRefresh'] = $true }
|    $tok = [string](Get-InvardiaSupportToken @p)
|    if ([string]::IsNullOrWhiteSpace($tok)) { throw ('The Invardia support session returned no token for {0}.' -f $Resource) }
|    $c = ConvertFrom-SIJwtPayload $tok
|    if (-not $c -or -not [string]$c.tid) { throw ('The Invardia support token for {0} could not be read (no tenant in it) -- refused.' -f $Resource) }
|    if ($TenantId -and [string]$c.tid -ne $TenantId) {
|        throw ('The Invardia support token for {0} is for tenant {1}, not {2} -- refused. Connect the support session of tenant {2}.' -f $Resource, $c.tid, $TenantId)
|    }
|    return $tok
|}
|
|function Get-SISupportAuth {
|    <# The Auth hashtable of the Invardia Support session: Mode 'Support', app + tenant + first subscription read from the
|       SESSION (Get-SISupportSession) -- no token is asked for. Refused when the session is for another tenant than
|       -TenantId / the configured one. ObjectId is not known here (Get-SISetupSignedInObjectId finds it when asked). #>
|    param([string]$TenantId)
|    $sess = Get-SISupportSession
|    if (-not $sess) { throw 'No Invardia Support session is open in this PowerShell session (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>'').' }
|    $want = Get-SISupportExpectedTenantId -TenantId $TenantId
|    if ($want -and $want -ne $sess.TenantId) {
|        throw ('The Invardia Support session for {0} is for tenant {1}, not {2} -- refused. Connect the support session of tenant {2}.' -f (Get-SISupportSessionName $sess), $sess.TenantId, $want)
|    }
|    return @{ Mode = 'Support'; AppId = [string]$sess.AppId; TenantId = [string]$sess.TenantId; ObjectId = $null; SubscriptionId = [string]$sess.SubscriptionId
|              Environment = [string]$sess.Environment; EnvironmentId = [string]$sess.EnvironmentId; SessionId = [string]$sess.SessionId }
|}
|
|function Sync-SISupportConnection {
|    <#
|        Keeps the recorded sign-in of this process in step with the Invardia Support session, and returns the session
|        ($null = none):
|          * no session, but the recorded sign-in is a Support one  -> the session was closed: the sign-in is dropped
|          * a session and no recorded sign-in (or one of ANOTHER session) -> the session becomes the sign-in
|          * a session and a recorded sign-in of SecurityInsight's own -> kept, unless -TakeOver (setup: a Support session
|            in the shell always wins there -- setup never works beside it with a sign-in of its own)
|        Says ONE plain line the first time a session is used. Throws what Get-SISupportSession / Get-SISupportAuth refuse.
|    #>
|    param([switch]$TakeOver)
|    $sess = Get-SISupportSession
|    $st = Get-SIAzRestState
|    $c = $st.Connection
|    $isSupport = ($c -is [hashtable]) -and ([string]$c.Mode -eq 'Support')
|    if (-not $sess) {
|        if ($isSupport) { $st.Connection = $null; $st.TenantId = $null; $st.SubscriptionId = $null; $st.Cache = @{} }
|        return $null
|    }
|    $same = $isSupport -and ([string]$c.TenantId -eq $sess.TenantId) -and ([string]$c.SessionId -eq $sess.SessionId) -and ([string]$c.EnvironmentId -eq $sess.EnvironmentId)
|    if ($same) { return $sess }
|    if (($c -is [hashtable]) -and -not $isSupport -and -not $TakeOver) { return $sess }
|    $st.Connection = Get-SISupportAuth
|    $st.TenantId = [string]$sess.TenantId
|    $st.Cache = @{}
|    if ($st.SubscriptionId -and @($sess.Subscriptions).Count -and @($sess.Subscriptions) -notcontains ([string]$st.SubscriptionId).Trim().ToLowerInvariant()) { $st.SubscriptionId = $null }
|    $key = '{0}|{1}|{2}' -f $sess.TenantId, $sess.EnvironmentId, $sess.SessionId
|    if ([string]$st['SupportSaid'] -ne $key) {
|        $st['SupportSaid'] = $key
|        Write-Host ('using the Invardia Support session for {0} -- every change is recorded there' -f (Get-SISupportSessionName $sess))
|    }
|    return $sess
|}
|
|function Test-SISupportRecorderPresent {
|    <# #548: is an Invardia Support session, with its RECORDING wrapper, open in this shell? (Get-SISupportSession decides.) #>
|    return [bool](Get-SISupportSession)
|}
|
|function Test-SISupportRequestRoute {
|    <#
|        #548 (Invardia, 2026-10-10: every Support app action is recorded in the customer's audit log): does a request for
|        -Audience, as -Auth (none = the run's own sign-in), go through Invardia's recording wrapper? Yes when a Support
|        session is open (Get-SISupportSession) AND the call is made as the support session (Mode 'Support' -- the recorded
|        sign-in, or no recorded sign-in at all) AND no host token provider ($global:SI_TokenProvider) answers instead.
|        Every audience SecurityInsight signs in to: Arm, Graph, Log Analytics, Storage, Exchange Online's admin API, Key
|        Vault and Azure Monitor -- on any host (a host the wrapper does not know by itself gets its token audience named,
|        Get-SISupportTokenResource). A URL that is none of these (-Audience Other: another service with its own key) is
|        not a call as the support app and never goes through it. -Uri is accepted for callers that pass it.
|    #>
|    param([string]$Audience = 'Arm', [hashtable]$Auth, [string]$Uri)
|    if ($Audience -notin 'Arm', 'Graph', 'LaQuery', 'Storage', 'Exchange', 'KeyVault', 'Monitor') { return $false }
|    if ($Auth) {
|        if ([string]$Auth.Mode -ne 'Support') { return $false }
|        return [bool](Get-SISupportSession)
|    }
|    $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|    if ($tp -is [scriptblock]) { return $false }
|    # a caller that loaded only part of this file (a script's own fakes, a lifted function) has no state helpers -- and no
|    # support session either
|    if (-not (Test-Path -LiteralPath 'Function:\Get-SIAzRestState')) { return $false }
|    if (-not (Test-Path -LiteralPath 'Function:\Sync-SISupportConnection')) { return $false }
|    if (-not (Sync-SISupportConnection)) { return $false }
|    $c = (Get-SIAzRestState).Connection
|    return (($c -is [hashtable]) -and ([string]$c.Mode -eq 'Support'))
|}
|
|function Get-SISupportTokenResource {
|    <# PURE. The token audience to NAME to the recording wrapper for a request it cannot name from the URL's host by
|       itself: a Key Vault or Azure Monitor URL on another host than <vault>.vault.azure.net /
|       <endpoint>.ingest.monitor.azure.com. '' = the wrapper names it (Arm, Graph, Log Analytics, Storage, Exchange). #>
|    param([string]$Audience, [string]$Uri)
|    $h = ''
|    try { $h = ([uri]$Uri).Host } catch { $h = '' }
|    if ($Audience -eq 'KeyVault' -and $h -notmatch '(?i)\.vault\.azure\.net$') { return 'https://vault.azure.net' }
|    if ($Audience -eq 'Monitor' -and $h -notmatch '(?i)\.ingest\.monitor\.azure\.com$') { return 'https://monitor.azure.com' }
|    return ''
|}
|
|function Test-SISupportReadOnlyPost {
|    <#
|        PURE. Is this POST a READ (recorded as a read, not as a change)? Only the POSTs known to change nothing:
|          ARM    Resource Graph (/providers/Microsoft.ResourceGraph/resources), a provider's checkNameAvailability, a
|                 workspace query (.../workspaces/<name>/query, /api/query)
|          Log Analytics   /v1/workspaces/<id>/query
|          Graph  getByIds, getMemberObjects, getMemberGroups, checkMemberObjects, checkMemberGroups, security/runHuntingQuery
|                 (a KQL hunting query), and a $batch whose
|                 requests are ALL GET
|        Anything else -- and anything not understood -- is a CHANGE. A GET / HEAD is a read by its method (not asked here).
|    #>
|    param([string]$Method, [string]$Uri, $Body)
|    if (([string]$Method).ToUpperInvariant() -ne 'POST') { return $false }
|    $u = $null
|    try { $u = [uri]$Uri } catch { return $false }
|    if (-not $u -or -not $u.IsAbsoluteUri) { return $false }
|    $h = $u.Host.ToLowerInvariant(); $p = $u.AbsolutePath
|    if ($h -match '^management\.(azure\.com|core\.windows\.net)$') {
|        if ($p -match '(?i)^/providers/Microsoft\.ResourceGraph/resources/?$') { return $true }
|        if ($p -match '(?i)/providers/[^/]+/checkNameAvailability/?$') { return $true }
|        if ($p -match '(?i)/providers/Microsoft\.OperationalInsights/workspaces/[^/]+/(api/)?query/?$') { return $true }
|        return $false
|    }
|    if ($h -eq 'api.loganalytics.io' -or $h -eq 'api.loganalytics.azure.com') { return [bool]($p -match '(?i)^/v1/workspaces/[^/]+/query/?$') }
|    if ($h -eq 'graph.microsoft.com') {
|        if ($p -match '(?i)/(getByIds|getMemberObjects|getMemberGroups|checkMemberObjects|checkMemberGroups)/?$') { return $true }
|        # Defender advanced hunting: a KQL query, which can only read
|        if ($p -match '(?i)^/(v1\.0|beta)/security/runHuntingQuery/?$') { return $true }
|        if ($p -match '(?i)^/(v1\.0|beta)/\$batch/?$') {
|            try {
|                $text = ''
|                if ($Body -is [byte[]]) { $text = [System.Text.Encoding]::UTF8.GetString($Body) } else { $text = [string]$Body }
|                $reqs = @(($text | ConvertFrom-Json).requests | Where-Object { $null -ne $_ })
|                if (-not $reqs.Count) { return $false }
|                return (-not @($reqs | Where-Object { ([string]$_.method).ToUpperInvariant() -ne 'GET' }).Count)
|            } catch { return $false }
|        }
|        return $false
|    }
|    return $false
|}
|
|function Test-SISupportBodyIsText {
|    <# PURE. Can -Body go through Invardia's recording wrapper? Yes for every body: the wrapper sends a [byte[]] body
|       unchanged (Invardia, 2026-10-10). Kept as the one place to say otherwise. #>
|    param($Body, [string]$ContentType)
|    return $true
|}
|
|function Invoke-SISupportHttp {
|    <#
|        #548: ONE HTTP exchange through Invardia's recording wrapper, in the shape of Invoke-SIAzRestHttp (StatusCode,
|        Content, Bytes, Headers, RetryAfter) so Invoke-SIAzRestRequest's retry and error rules stay exactly as they are
|        (an HTTP status >= 400 becomes SecurityInsight's own error there). The wrapper adds the support app's token: an
|        Authorization header of the caller is dropped. No answer = StatusCode 0 (retried like any network failure); a
|        refusal to record the action in the customer's audit log is RETHROWN (fail-closed: the action was not made).
|        A GET / HEAD is a read by its method; a POST that only reads (Test-SISupportReadOnlyPost) is sent -ReadOnly;
|        everything else is recorded as a change. An Azure Resource Manager URL of a subscription the session's environment
|        does not name is REFUSED before anything is sent (Assert-SISupportSubscription). -Audience names the token audience
|        for a host the wrapper does not know (Get-SISupportTokenResource); -TimeoutSec is passed on.
|    #>
|    param([Parameter(Mandatory)][string]$Method, [Parameter(Mandatory)][string]$Uri, [hashtable]$Headers, $Body, [string]$ContentType, [switch]$AsBytes,
|          [string]$Audience, [int]$TimeoutSec = 0)
|    $sess = Get-SISupportSession
|    if (-not $sess) { throw 'No Invardia support session is open in this PowerShell session, so this request cannot be sent through it.' }
|    $target = $null
|    try { $target = [uri]$Uri } catch { $target = $null }
|    if ($target -and $target.IsAbsoluteUri -and $target.Host -match '(?i)^management\.(azure\.com|core\.windows\.net)$' -and
|        $target.AbsolutePath -match '(?i)^/subscriptions/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(/|$)') {
|        Assert-SISupportSubscription -SubscriptionId $Matches[1] -Session $sess
|    }
|    $h = @{}
|    if ($Headers) { foreach ($k in @($Headers.Keys)) { if ([string]$k -ine 'Authorization' -and [string]$k -ine 'Content-Type') { $h[[string]$k] = $Headers[$k] } elseif ([string]$k -ieq 'Content-Type' -and -not $ContentType) { $ContentType = [string]$Headers[$k] } } }
|    $p = @{ Method = $Method.ToUpperInvariant(); Uri = $Uri }
|    if ($h.Count) { $p.Headers = $h }
|    if ($null -ne $Body) {
|        # bytes go unchanged (a source package upload). NOT $(if ...): a subexpression ENUMERATES the byte array into an
|        # object[] -- the wrapper then sent it as JSON numbers instead of the file
|        if ($Body -is [byte[]]) { $p.Body = $Body } else { $p.Body = [string]$Body }
|        if ($ContentType) { $p.ContentType = $ContentType }
|    }
|    $o = $null
|    if ($AsBytes) { $p.AsBytes = $true }   # the raw answer as ContentBytes (a download)
|    if (Test-SISupportReadOnlyPost -Method $Method -Uri $Uri -Body $Body) { $p.ReadOnly = $true }   # a POST that only reads
|    if ($TimeoutSec -gt 0) { $p.TimeoutSec = $TimeoutSec }
|    $tokenResource = Get-SISupportTokenResource -Audience $Audience -Uri $Uri
|    if ($tokenResource) { $p.TokenResource = $tokenResource }
|    try { $o = Invoke-InvardiaSupportRequest @p }
|    catch {
|        $m = [string]$_.Exception.Message
|        if ($m -match '(?i)audit log|fail-closed|could not be recorded|No Invardia support session') { throw }
|        return [pscustomobject]@{ StatusCode = 0; Content = $m; Bytes = $null; Headers = @{}; RetryAfter = $null }
|    }
|    $hh = New-Object 'System.Collections.Hashtable' ([System.StringComparer]::OrdinalIgnoreCase)
|    if ($o -and $o.Headers) {
|        try {
|            if ($o.Headers -is [System.Collections.IDictionary]) { foreach ($k in @($o.Headers.Keys)) { $hh[[string]$k] = (@($o.Headers[$k]) | ForEach-Object { [string]$_ }) -join ',' } }
|            else { foreach ($k in @($o.Headers.AllKeys)) { $hh[[string]$k] = [string]$o.Headers[$k] } }
|        } catch { }
|    }
|    $text = if ($o) { [string]$o.Content } else { '' }
|    # the raw answer as [byte[]] -- assigned in statements, never through $( ... ), which would enumerate it into object[]
|    [byte[]]$raw = $null
|    if ($AsBytes) {
|        if ($o -and $o.PSObject.Properties['ContentBytes'] -and $o.ContentBytes) { $raw = [byte[]]$o.ContentBytes } else { $raw = [System.Text.Encoding]::UTF8.GetBytes($text) }
|    }
|    $out = [pscustomobject]@{
|        StatusCode = $(if ($o) { [int]$o.StatusCode } else { 0 }); Content = $(if ($AsBytes) { '' } else { $text })
|        Bytes = $null; Headers = $hh; RetryAfter = [string]$hh['Retry-After']
|    }
|    $out.Bytes = $raw
|    $out
|}
|
|function Invoke-SIRestMethod {
|    <#
|        #548: the drop-in for Invoke-RestMethod that setup's own Graph / ARM calls use (-Method, -Uri, -Headers with the
|        caller's bearer token, -Body, -ContentType): inside an Invardia support session the call goes through the recording
|        wrapper (the caller's Authorization header is dropped -- the wrapper signs as the support app); otherwise exactly
|        Invoke-RestMethod. Throws on HTTP >= 400 like Invoke-RestMethod, with the service's answer in the message; returns
|        the parsed JSON (or the text when it is not JSON).
|    #>
|    [CmdletBinding()]   # -ErrorAction and the other common parameters, as Invoke-RestMethod callers pass them
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Uri, [hashtable]$Headers, $Body, [string]$ContentType, [int]$TimeoutSec = 120)
|    $host_ = ([uri]$Uri).Host
|    $aud = if ($host_ -eq 'graph.microsoft.com') { 'Graph' } elseif ($host_ -match '^management\.(azure\.com|core\.windows\.net)$') { 'Arm' } elseif ($host_ -eq 'api.loganalytics.io') { 'LaQuery' } elseif ($host_ -eq 'outlook.office365.com') { 'Exchange' } else { 'Other' }
|    # this function is published GLOBALLY: a caller that never loaded this file (a script run on its own, a test with its
|    # own fakes) has no routing helpers -- and then no support session either: plain Invoke-RestMethod
|    if ((Test-Path -LiteralPath 'Function:\Test-SISupportRequestRoute') -and (Test-SISupportRequestRoute -Audience $aud)) {
|        $b = $Body
|        if ($null -ne $b -and -not ($b -is [string]) -and -not ($b -is [byte[]])) { $b = ConvertTo-Json -InputObject $b -Depth 30 -Compress }
|        $ct = if ($ContentType) { $ContentType } elseif ($null -ne $b) { 'application/json' } else { '' }
|        $r = Invoke-SISupportHttp -Method $Method -Uri $Uri -Headers $Headers -Body $b -ContentType $ct -Audience $aud -TimeoutSec $TimeoutSec
|        $code = [int]$r.StatusCode
|        if ($code -lt 200 -or $code -ge 300) {
|            throw (New-SIAzRestError -Message ('{0} {1} failed. HTTP Status: {2} ({3}) Response: {4}' -f $Method.ToUpperInvariant(), ($Uri -replace '\?.*$', ''), $code, (Get-SIAzRestStatusName $code), $r.Content) -Response $r)
|        }
|        $t = [string]$r.Content
|        if (-not $t.Trim()) { return $null }
|        try { return ($t | ConvertFrom-Json) } catch { return $t }
|    }
|    $a = @{ Method = $Method; Uri = $Uri; ErrorAction = 'Stop'; TimeoutSec = $TimeoutSec }
|    if ($Headers) { $a.Headers = $Headers }
|    if ($null -ne $Body) { $a.Body = $Body }
|    if ($ContentType) { $a.ContentType = $ContentType }
|    Invoke-RestMethod @a
|}
|# published globally: a product script the install runs (in this process) finds it even when it loaded only part of the layer
|Set-Item -Path 'function:global:Invoke-SIRestMethod' -Value ${function:Invoke-SIRestMethod}
|
|# =====================================================================================================================
|#  The wrapper map, shared state
|# =====================================================================================================================
|
|function Get-SIAzRestWrapperMap {
|    <# wrapper -> the Az cmdlet it replaces -> its REST twin, as data. The wiring tests read it. #>
|    $m = [ordered]@{}
|    foreach ($az in @(
|        'Connect-AzAccount', 'Disconnect-AzAccount', 'Disable-AzContextAutosave', 'Get-AzContext', 'Set-AzContext',
|        'Get-AzAccessToken', 'Get-AzSubscription', 'Invoke-AzRestMethod',
|        'Invoke-AzOperationalInsightsQuery', 'Get-AzOperationalInsightsWorkspace', 'New-AzOperationalInsightsWorkspace',
|        'Search-AzGraph', 'Get-AzKeyVaultSecret', 'Set-AzKeyVaultSecret',
|        'Get-AzResourceGroup', 'New-AzResourceGroup', 'Get-AzRoleAssignment', 'New-AzRoleAssignment', 'Get-AzRoleDefinition',
|        'Get-AzTag', 'Update-AzTag', 'Get-AzADServicePrincipal',
|        'Get-AzDataCollectionEndpoint', 'New-AzDataCollectionEndpoint', 'Get-AzDataCollectionRule',
|        'New-AzStorageContext', 'Get-AzStorageAccount', 'New-AzStorageAccount',
|        'Get-AzStorageContainer', 'New-AzStorageContainer', 'Get-AzStorageBlob', 'Get-AzStorageBlobContent',
|        'Set-AzStorageBlobContent', 'Remove-AzStorageBlob', 'Start-AzStorageBlobCopy',
|        'Get-AzStorageQueue', 'New-AzStorageQueue')) {
|        $w = $az -replace '-Az', '-SIAz'
|        $m[$w] = @{ Replaces = $az; Rest = ($w + 'Rest') }
|    }
|    return $m
|}
|
|function Get-SIAzRestState {
|    <# Per-process state: the recorded sign-in, the current subscription, token / lookup caches. Global because this
|       file is dot-sourced at different depths by different engines. #>
|    # StrictMode-safe: an unset global is read through Get-Variable, never directly (a caller may run Set-StrictMode).
|    if (-not ((Get-Variable -Scope Global -Name SI_AzRestState -ValueOnly -ErrorAction Ignore) -is [hashtable])) {
|        $global:SI_AzRestState = @{ Connection = $null; SubscriptionId = $null; TenantId = $null; Cache = @{} }
|    }
|    return $global:SI_AzRestState
|}
|
|function Initialize-SIAzRestHelpers {
|    <# The token functions (SI-LogIngest.ps1), the KQL error reader (SI-KqlError.ps1) and the certificate helpers
|       (auth/Find-SICertificate.ps1). Loaded on first need; only what is MISSING is loaded and published globally, so a
|       caller's own copy or a test's mock is never replaced. #>
|    $want = @(
|        @{ Path = (Join-Path $PSScriptRoot 'SI-LogIngest.ps1'); Fns = @('Get-SILogIngestToken', 'Invoke-SILogIngestHttp', 'Get-SILogIngestRunCache', 'Get-SILogIngestRetryDelay', 'Initialize-SILogIngestAuthHelpers') }
|        @{ Path = (Join-Path $PSScriptRoot 'SI-KqlError.ps1');   Fns = @('Get-SIKqlErrorText', 'Get-SIKqlErrorSummary', 'Test-SIKqlTableMissing') }
|        @{ Path = (Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth/Find-SICertificate.ps1'); Fns = @('Get-SICertificateClientToken', 'Get-SICertificateFromStore', 'Test-SICertDriveAvailable') }
|    )
|    foreach ($w in $want) {
|        $missing = @($w.Fns | Where-Object { -not (Get-Command -Name $_ -ErrorAction Ignore) })
|        if ($missing.Count -eq 0) { continue }
|        if (-not (Test-Path -LiteralPath $w.Path)) { continue }
|        . $w.Path
|        foreach ($n in $missing) {
|            $f = Get-Command -Name $n -CommandType Function -ErrorAction Ignore
|            if ($f) { Set-Item -Path ("function:global:{0}" -f $n) -Value $f.ScriptBlock }
|        }
|    }
|}
|
|# =====================================================================================================================
|#  HTTP seam, sign-in, tokens
|# =====================================================================================================================
|
|function Remove-SIAzRestCaughtError {
|    <# Takes a HANDLED error record back out of $global:Error (newest entries only). PS 5.1 safe. #>
|    param($Record)
|    if ($null -eq $Record) { return }
|    $errs = $global:Error
|    for ($i = 0; $i -lt [Math]::Min(3, $errs.Count); $i++) {
|        $e = $errs[$i]
|        if ([object]::ReferenceEquals($e, $Record) -or ($e -is [System.Management.Automation.ErrorRecord] -and $Record -is [System.Management.Automation.ErrorRecord] -and [object]::ReferenceEquals($e.Exception, $Record.Exception))) {
|            $errs.RemoveAt($i); return
|        }
|    }
|}
|
|function Invoke-SIAzRestHttp {
|    <#
|        THE ONE HTTP SEAM of this file (tests Mock it). Never throws on an HTTP status: returns
|        @{ StatusCode; Content; Bytes; Headers; RetryAfter }. A network failure (no response) is StatusCode 0.
|        HttpWebRequest, not Invoke-WebRequest: the 4xx body and headers read the same way on PS 5.1 and pwsh 7.
|        -AsBytes keeps the body as bytes (blob downloads); Content is then ''.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Method,
|        [Parameter(Mandatory)][string]$Uri,
|        [hashtable]$Headers,
|        $Body,
|        [string]$ContentType,
|        [int]$TimeoutSec = 300,
|        [switch]$AsBytes,
|        # A 2xx body read AS IT ARRIVES (SI-LaStreamRead.ps1): { param([IO.Stream]$Stream) <the parsed answer> } -- the body
|        # is never held whole; the answer is returned as .Parsed (Content '', Bytes $null). Any other status: as without it.
|        [scriptblock]$ReadStream
|    )
|    if ($PSVersionTable.PSEdition -ne 'Core') {
|        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
|    }
|    $req = [System.Net.HttpWebRequest]::Create($Uri)
|    $req.Method = $Method.ToUpperInvariant()
|    $req.Timeout = $TimeoutSec * 1000
|    $req.ReadWriteTimeout = $TimeoutSec * 1000
|    $req.Accept = 'application/json'
|    if ($Headers) {
|        foreach ($k in $Headers.Keys) {
|            if ($k -eq 'Content-Type') { $req.ContentType = [string]$Headers[$k] }
|            elseif ($k -eq 'Accept')   { $req.Accept = [string]$Headers[$k] }
|            else { $req.Headers[$k] = [string]$Headers[$k] }
|        }
|    }
|    if ($ContentType) { $req.ContentType = $ContentType }
|    if ($null -ne $Body) {
|        # statements, never `= if (...) { $Body }`: an if-expression ENUMERATES a byte array into object[] (one boxed object
|        # per byte) -- a build context of tens of MB became gigabytes and the updater ran out of memory
|        [byte[]]$bytes = $null
|        if ($Body -is [byte[]]) { $bytes = $Body } else { $bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$Body) }
|        $req.ContentLength = $bytes.Length
|        # A connection that fails while the BODY is sent (connect, DNS, reset) is "no answer" (StatusCode 0), which the caller
|        # retries -- for a request that is safe to send again (PUT / PATCH / DELETE / MERGE: idempotent, as an ARM or table PUT
|        # is). A POST that failed here is thrown as before: it is not repeated blindly. (The sweep of 2026-10-22: this threw
|        # past every retry loop on blob, table and ARM writes.)
|        try {
|            $s = $req.GetRequestStream()
|            try { $s.Write($bytes, 0, $bytes.Length) } finally { $s.Close() }
|        } catch {
|            if ($req.Method -eq 'POST') { throw }
|            return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; Bytes = $null; Headers = @{}; RetryAfter = $null }
|        }
|    } elseif ($req.Method -in 'POST', 'PUT', 'PATCH', 'MERGE') {
|        $req.ContentLength = 0
|    }
|    $resp = $null
|    try { $resp = $req.GetResponse() }
|    catch {
|        $we = $_.Exception
|        while ($we -and -not ($we -is [System.Net.WebException])) { $we = $we.InnerException }
|        if ($we -and $we.Response) {
|            $resp = $we.Response
|            # An HTTP status is an ANSWER, returned to the caller (who decides whether a 404 is "not there" or a failure)
|            # -- not an error of this process. PowerShell still records the caught exception in $Error, and setup shows
|            # every new $Error entry: each "does it exist?" probe printed "(404) Not Found" (live 2026-10-06). Drop it.
|            Remove-SIAzRestCaughtError -Record $_
|        }
|        else { return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; Bytes = $null; Headers = @{}; RetryAfter = $null } }
|    }
|    try {
|        $h = New-Object 'System.Collections.Hashtable' ([System.StringComparer]::OrdinalIgnoreCase)
|        foreach ($k in $resp.Headers.AllKeys) { $h[$k] = [string]$resp.Headers[$k] }
|        $text = ''; $raw = $null
|        $rs = $resp.GetResponseStream()
|        $sc = [int]$resp.StatusCode
|        if ($rs -and $ReadStream -and $sc -ge 200 -and $sc -lt 300) {
|            $parsed = $null
|            try { $parsed = & $ReadStream $rs } finally { $rs.Close() }
|            return [pscustomobject]@{ StatusCode = $sc; Content = ''; Bytes = $null; Headers = $h; RetryAfter = [string]$h['Retry-After']; Parsed = $parsed }
|        }
|        if ($rs) {
|            # #639: the body is read ONCE into an array of its own length when the service says how long it is -- not into a
|            # growing buffer that is then copied again (a large answer was held two or three times before it was parsed)
|            try {
|                $len = [long]$resp.ContentLength
|                if ($len -gt 0 -and $len -lt [int]::MaxValue) {
|                    $raw = [byte[]]::new([int]$len); $off = 0
|                    while ($off -lt $len) { $n = $rs.Read($raw, $off, [int]($len - $off)); if ($n -le 0) { break }; $off += $n }
|                    if ($off -lt $len) { $part = [byte[]]::new($off); [Array]::Copy($raw, $part, $off); $raw = $part; $part = $null }
|                } else {
|                    $ms = New-Object System.IO.MemoryStream
|                    $rs.CopyTo($ms); $raw = $ms.ToArray(); $ms.Dispose(); $ms = $null
|                }
|            } finally { $rs.Close() }
|            if (-not $AsBytes) { $text = [System.Text.Encoding]::UTF8.GetString($raw); $raw = $null }
|        }
|        return [pscustomobject]@{ StatusCode = [int]$resp.StatusCode; Content = $text; Bytes = $raw; Headers = $h; RetryAfter = [string]$h['Retry-After'] }
|    } finally { $resp.Close() }
|}
|
|function Get-SIAzRestValue {
|    <# The first non-empty global of -Names. #>
|    param([string[]]$Names)
|    foreach ($n in $Names) {
|        $v = Get-Variable -Scope Global -Name $n -ValueOnly -ErrorAction Ignore
|        if ($null -ne $v -and -not [string]::IsNullOrWhiteSpace([string]$v)) { return [string]$v }
|    }
|    return $null
|}
|
|function Resolve-SIAzRestAuth {
|    <#
|        WHO this run signs in as, for the REST path:
|          1. what Connect-SIAzAccount recorded in this process (the launcher / container entry point decided)
|          1b. an Invardia Support session open in this shell (Mode 'Support', read from the session)
|          2. the run's managed-identity switch (SI_UseManagedIdentity / UseManagedIdentity, #222)
|          3. an SPN certificate   (SI_SPN_AppId | SpnClientId | HighPriv_* + SI_SPN_CertThumbprint | SpnCertificateThumbprint)
|          4. an SPN client secret (SI_SPN_Secret | SpnClientSecret | HighPriv_*)
|        Certificate before secret, as everywhere in SecurityInsight. Returns the Auth hashtable Get-SILogIngestToken
|        takes. Throws when nothing is configured -- the REST path never falls back to an Az session.
|    #>
|    # An Invardia Support session in this shell: it IS the sign-in when nothing else was recorded (and a Support sign-in
|    # whose session was closed is dropped) -- Sync-SISupportConnection, read from the session, no token asked for.
|    $null = Sync-SISupportConnection
|    $st = Get-SIAzRestState
|    if ($st.Connection -is [hashtable]) { return $st.Connection }
|    # #524: the retired sign-in mode "AzContext" (borrow this process's Azure session) is refused by name
|    if ([string](Get-Variable -Scope Global -Name SI_AuthMethod -ValueOnly -ErrorAction Ignore) -eq 'AzContext') {
|        throw ('SI_AuthMethod = AzContext (use the current Azure session of this PowerShell process) is no longer supported: SecurityInsight signs in itself. Supported sign-ins: {0}.' -f (Get-SISupportedSignInText))
|    }
|    if ([bool](Get-Variable -Scope Global -Name SI_UseManagedIdentity -ValueOnly -ErrorAction Ignore) -or [bool](Get-Variable -Scope Global -Name UseManagedIdentity -ValueOnly -ErrorAction Ignore)) {
|        return @{ Mode = 'ManagedIdentity'; ClientId = [string](Get-SIAzRestValue 'SI_UAMI_ClientId', 'SI_ManagedIdentityClientId') }
|    }
|    $tid   = Get-SIAzRestValue 'SI_SPN_TenantId', 'SpnTenantId', 'HighPriv_Modern_TenantID', 'AzureTenantId', 'TenantId'
|    $app   = Get-SIAzRestValue 'SI_SPN_AppId', 'SpnClientId', 'HighPriv_Modern_ApplicationID_Azure'
|    $thumb = Get-SIAzRestValue 'SI_SPN_CertThumbprint', 'SpnCertificateThumbprint', 'HighPriv_Modern_CertificateThumbprint_Azure'
|    $sec   = Get-SIAzRestValue 'SI_SPN_Secret', 'SpnClientSecret', 'HighPriv_Modern_Secret_Azure', 'HighPriv_Modern_ApplicationSecret_Azure'
|    if ($app -and $thumb -and $tid) { return @{ Mode = 'Certificate'; AppId = $app; TenantId = $tid; Thumbprint = ($thumb -replace '\s', '') } }
|    if ($app -and $sec -and $tid)   { return @{ Mode = 'Secret'; AppId = $app; TenantId = $tid; Secret = $sec } }
|    throw ('No sign-in is configured for Azure access over REST. Supported sign-ins: {0}.' -f (Get-SISupportedSignInText))
|}
|
|function Get-SIAzureAudience {
|    <# The token resource of each audience the REST path talks to. #>
|    param([Parameter(Mandatory)][ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience)
|    switch ($Audience) {
|        'Arm'      { 'https://management.azure.com/' }
|        'LaQuery'  { 'https://api.loganalytics.io/' }
|        'Storage'  { 'https://storage.azure.com/' }
|        'KeyVault' { 'https://vault.azure.net/' }
|        'Graph'    { 'https://graph.microsoft.com/' }
|        'Monitor'  { 'https://monitor.azure.com/' }
|    }
|}
|
|function Get-SIAzureToken {
|    <#
|        ONE token function for every audience: a bearer token as the identity Resolve-SIAzRestAuth names, minted by
|        Get-SILogIngestToken (managed identity endpoint / certificate client assertion / client secret), cached per
|        identity + audience until 5 minutes before expiry. -Audience or a raw -Resource; -Auth overrides the identity.
|    #>
|    param(
|        [ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience = 'Arm',
|        [string]$Resource,
|        [hashtable]$Auth,
|        [switch]$ForceRefresh
|    )
|    if (-not $Resource) { $Resource = Get-SIAzureAudience -Audience $Audience }
|    # A host that signs in its own way (setup, a test) can supply tokens: $global:SI_TokenProvider = { param($Resource) <token> }.
|    # Consulted first, only when no explicit -Auth was passed; an empty answer falls through to SecurityInsight's own sign-in.
|    if (-not $Auth) {
|        $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|        if ($tp -is [scriptblock]) { $pt = [string](& $tp $Resource); if (-not [string]::IsNullOrWhiteSpace($pt)) { return $pt } }
|    }
|    Initialize-SIAzRestHelpers
|    if (-not $Auth) { $Auth = Resolve-SIAzRestAuth }
|    return (Get-SILogIngestToken -Resource $Resource -Auth $Auth -ForceRefresh:$ForceRefresh)
|}
|
|function ConvertFrom-SIJwtPayload {
|    <# PURE. The claims of a JWT (no signature check -- only used to read tid / exp / appid of our own token). #>
|    param([string]$Token)
|    $parts = ([string]$Token) -split '\.'
|    if ($parts.Count -lt 2) { return $null }
|    $p = $parts[1].Replace('-', '+').Replace('_', '/')
|    switch ($p.Length % 4) { 2 { $p += '==' } 3 { $p += '=' } }
|    try { return ([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json) } catch { return $null }
|}
|
|function New-SIAzRestError {
|    <# An exception carrying the service's response (Response.StatusCode / Content / Headers), so the existing readers
|       (Get-SIKqlErrorText, the ledger's 412 match, ...) find what the service said. #>
|    param([string]$Message, $Response)
|    $ex = New-Object System.Exception($Message)
|    if ($Response) {
|        $r = [pscustomobject]@{ StatusCode = [int]$Response.StatusCode; Content = [string]$Response.Content; Headers = $Response.Headers }
|        Add-Member -InputObject $ex -NotePropertyName Response -NotePropertyValue $r -Force
|    }
|    return $ex
|}
|
|function Get-SIAzRestStatusName {
|    param([int]$Code)
|    if ($Code -le 0) { return 'NoResponse' }
|    try { return [string][System.Net.HttpStatusCode]$Code } catch { return [string]$Code }
|}
|
|function Invoke-SIAzRestRequest {
|    <#
|        One authenticated REST call with the retry rule:
|          429 / 408 / 5xx / no response -> PLATFORM: wait (Retry-After when sent) and retry in-run
|          401 once                      -> refresh the token, repeat once
|          404 with -AllowNotFound       -> $null
|          any other 4xx                 -> FAIL FAST with the body
|        Returns the response (StatusCode / Content / Bytes / Headers).
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Uri,
|        [ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience = 'Arm',
|        $Body,
|        [string]$ContentType = 'application/json',
|        [hashtable]$Headers,
|        [switch]$AllowNotFound,
|        [int[]]$AllowStatus = @(),
|        [switch]$AsBytes,
|        [int]$TimeoutSec = 300,
|        [int]$MaxAttempts = 6,
|        [string]$What = 'Azure request',
|        [hashtable]$Auth,  # another identity than the run's (the platform sign-in reads its Key Vault as the bootstrap identity)
|        # a 2xx body read as it arrives (Invoke-SIAzRestHttp -ReadStream); not through an Invardia support session, whose
|        # recording wrapper hands the answer back whole
|        [scriptblock]$ReadStream
|    )
|    $refreshed = $false; $force = $false
|    # #548: inside an Invardia support session every call SecurityInsight makes as the support app goes through Invardia's
|    # RECORDING wrapper (Invoke-InvardiaSupportRequest: the customer's audit log, fail-closed) -- never a raw token + HTTP.
|    # Every body and every answer goes through the wrapper: a binary body is sent unchanged, a binary answer (a download)
|    # comes back as its ContentBytes (Invardia, 2026-10-10).
|    $viaSupport = (Test-SISupportBodyIsText -Body $Body -ContentType $ContentType) -and (Test-SISupportRequestRoute -Audience $Audience -Auth $Auth -Uri $Uri)
|    for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
|        if ($viaSupport) {
|            $h = @{}
|            if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|            $r = Invoke-SISupportHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -AsBytes:$AsBytes -Audience $Audience -TimeoutSec $TimeoutSec
|        } else {
|            $token = Get-SIAzureToken -Audience $Audience -Auth $Auth -ForceRefresh:$force
|            $force = $false
|            $h = @{ 'Authorization' = ('Bearer ' + $token) }
|            if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|            if ($ReadStream) { $r = Invoke-SIAzRestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -TimeoutSec $TimeoutSec -AsBytes:$AsBytes -ReadStream $ReadStream }
|            else { $r = Invoke-SIAzRestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -TimeoutSec $TimeoutSec -AsBytes:$AsBytes }
|        }
|        $code = [int]$r.StatusCode
|        if ($code -ge 200 -and $code -lt 300) { return $r }
|        if ($AllowStatus -contains $code) { return $r }
|        if ($code -eq 404 -and $AllowNotFound) { return $null }
|        if ($code -eq 401 -and -not $refreshed) { $refreshed = $true; $force = $true; continue }
|        $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|        if ($transient -and $attempt -lt $MaxAttempts) {
|            Initialize-SIAzRestHelpers
|            $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|            Write-Verbose ("{0}: HTTP {1}, retrying in {2}s (attempt {3}/{4})" -f $What, $code, $wait, $attempt, $MaxAttempts)
|            Start-Sleep -Seconds $wait
|            continue
|        }
|        $body = [string]$r.Content
|        if ($AsBytes -and $r.Bytes) { try { $body = [System.Text.Encoding]::UTF8.GetString($r.Bytes) } catch { } }
|        $errCode = ''
|        if ($r.Headers -and $r.Headers['x-ms-error-code']) { $errCode = ' ' + [string]$r.Headers['x-ms-error-code'] }
|        $resp = [pscustomobject]@{ StatusCode = $code; Content = $body; Headers = $r.Headers }
|        throw (New-SIAzRestError -Message ("{0} failed. HTTP Status: {1} ({2}){3} Response: {4}" -f $What, $code, (Get-SIAzRestStatusName $code), $errCode, $body) -Response $resp)
|    }
|    throw ("{0} failed after {1} attempts." -f $What, $MaxAttempts)
|}
|
|# =====================================================================================================================
|#  ARM, Resource Graph, Key Vault, Log Analytics
|# =====================================================================================================================
|
|function Test-SIArmBusyError {
|    <# PURE. #564: an ARM refusal that means "another operation on this resource is still running" (HTTP 409
|       OperationInProgress and its per-service names) -- a wait, not a failure. A plain 409 Conflict ("already exists") is NOT. #>
|    param([AllowEmptyString()][string]$Message)
|    [bool]("$Message" -match '(?i)\w*OperationInProgress|operation is (still )?in progress|another operation is (in progress|ongoing|running)|active provisioning operation|is currently being (updated|provisioned)')
|}
|
|function Invoke-SIArmWriteBusyRetry {
|    <#
|        #564 (PIM's install at customer I, 2026-10-10): ONE ARM write (PUT / PATCH / POST / DELETE) with a BOUNDED wait for a busy
|        resource: a write seconds after another change to the same resource is refused "409 OperationInProgress". Waits
|        $global:SI_ArmBusyWaits (default 6 x 20 s) between attempts, RE-READS the resource before each retry (PUT / PATCH /
|        DELETE: what Azure has now), and after a write that had to wait READS IT BACK until it is provisioned (about 60 s).
|        Any other failure is rethrown at once WITH ITS OWN ERROR; the last busy failure is rethrown after the last wait.
|        NOT a closure (a GetNewClosure() block cannot see the functions this file defines). $global:SI_ArmBusySleep
|        { param($Seconds) } is the test seam for the waits. Returns the response (Invoke-SIAzRestRequest's shape).
|    #>
|    param([Parameter(Mandatory)][string]$Method, [Parameter(Mandatory)][string]$Uri, $Json, [switch]$AllowNotFound, [string]$What = 'Azure Resource Manager write')
|    $waits = @(20, 20, 20, 20, 20, 20)
|    $gw = Get-Variable -Scope Global -Name SI_ArmBusyWaits -ValueOnly -ErrorAction Ignore
|    if ($null -ne $gw) { $waits = @($gw | ForEach-Object { [int]$_ }) }
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    $verb = $Method.ToUpperInvariant()
|    $resourceUri = if ($verb -in 'PUT', 'PATCH', 'DELETE') { $Uri } else { $null }
|    $try = 0; $waited = $false
|    while ($true) {
|        try { $r = Invoke-SIAzRestRequest -Method $Method -Uri $Uri -Body $Json -AllowNotFound:$AllowNotFound -What $What; break }
|        catch {
|            if (-not (Test-SIArmBusyError -Message ([string]$_.Exception.Message)) -or $try -ge $waits.Count) { throw }
|            $w = [int]$waits[$try]; $try++; $waited = $true
|            Write-Host ('       Azure is still busy with another change to {0} -- waiting {1} s, then trying again ({2}/{3}) ...' -f (($Uri -replace '\?.*$', '') -split '/')[-1], $w, $try, $waits.Count) -ForegroundColor DarkYellow
|            if ($w -gt 0) { if ($sleep -is [scriptblock]) { & $sleep $w } else { Start-Sleep -Seconds $w } }
|            # re-read before the retry: what Azure has now (never fails the write -- the retry decides)
|            if ($resourceUri) { try { $null = Invoke-SIAzRestRequest -Method GET -Uri $resourceUri -AllowNotFound -What ('Reading ' + $What) } catch { } }
|        }
|    }
|    if ($waited -and $verb -in 'PUT', 'PATCH') {
|        # read back: the write that waited is followed until Azure has provisioned it (bounded, about 60 s)
|        for ($i = 0; $i -lt 6; $i++) {
|            $back = $null
|            try { $back = Invoke-SIAzRestRequest -Method GET -Uri $resourceUri -AllowNotFound -What ('Reading back ' + $What) } catch { break }
|            $ps = ''
|            try { $ps = [string](($back.Content | ConvertFrom-Json).properties.provisioningState) } catch { $ps = '' }
|            if (-not $ps -or $ps -in 'Succeeded', 'Failed', 'Canceled', 'Cancelled') { break }
|            if ($sleep -is [scriptblock]) { & $sleep 10 } else { Start-Sleep -Seconds 10 }
|        }
|    }
|    $r
|}
|
|function Invoke-SIArm {
|    <#
|        Azure Resource Manager. -Path is '/subscriptions/...' (or a full https:// URL, e.g. a nextLink); -ApiVersion is
|        appended when the path has none. Returns the parsed body ($null for a 404 with -AllowNotFound).
|        -List returns every item of a list, following nextLink.
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Path,
|        [string]$ApiVersion,
|        $Body,
|        [switch]$AllowNotFound,
|        [switch]$List
|    )
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path }
|    if ($ApiVersion -and $uri -notmatch '[?&]api-version=') { $uri += $(if ($uri -match '\?') { '&' } else { '?' }) + 'api-version=' + $ApiVersion }
|    $json = if ($null -ne $Body -and -not ($Body -is [string])) { $Body | ConvertTo-Json -Depth 50 -Compress } else { $Body }
|    # #564 (PIM's install at customer I, 2026-10-10): an ARM POST ACTION with no body (listSecrets, listCredentials, listKeys,
|    # sharedKeys, a revision restart, a provider register) sends '{}' -- an empty body with a JSON content type was
|    # refused with HTTP 415.
|    if ($Method.ToUpperInvariant() -eq 'POST' -and ($null -eq $json -or ([string]$json) -eq '')) { $json = '{}' }
|    $what = 'Azure Resource Manager {0} {1}' -f $Method, ($uri -replace '\?.*$', '')
|    if (-not $List) {
|        if ($Method.ToUpperInvariant() -eq 'GET') { $r = Invoke-SIAzRestRequest -Method $Method -Uri $uri -Body $json -AllowNotFound:$AllowNotFound -What $what }
|        else { $r = Invoke-SIArmWriteBusyRetry -Method $Method -Uri $uri -Json $json -AllowNotFound:$AllowNotFound -What $what }
|        if (-not $r -or [string]::IsNullOrWhiteSpace([string]$r.Content)) { return $null }
|        return ($r.Content | ConvertFrom-Json)
|    }
|    $items = [System.Collections.Generic.List[object]]::new()
|    $next = $uri
|    while ($next) {
|        $r = Invoke-SIAzRestRequest -Method 'GET' -Uri $next -AllowNotFound:$AllowNotFound -What $what
|        if (-not $r) { break }
|        $page = $r.Content | ConvertFrom-Json
|        foreach ($v in @($page.value)) { if ($null -ne $v) { [void]$items.Add($v) } }
|        $next = [string]$page.nextLink
|    }
|    return $items.ToArray()
|}
|
|function Search-SIResourceGraph {
|    <# Resource Graph: EVERY row of -Query, following $skipToken. -Subscription / -ManagementGroup scope it; neither =
|       every subscription the identity can read (as Search-AzGraph without them). #>
|    param(
|        [Parameter(Mandatory)][string]$Query,
|        [string[]]$Subscription,
|        [string[]]$ManagementGroup,
|        [int]$PageSize = 1000
|    )
|    $rows = [System.Collections.Generic.List[object]]::new()
|    $skip = $null
|    do {
|        $page = Invoke-SIResourceGraphPage -Query $Query -Subscription $Subscription -ManagementGroup $ManagementGroup -First $PageSize -SkipToken $skip
|        foreach ($d in @($page.Data)) { if ($null -ne $d) { [void]$rows.Add($d) } }
|        $skip = [string]$page.SkipToken
|    } while ($skip)
|    return $rows.ToArray()
|}
|
|function Invoke-SIResourceGraphPage {
|    <# ONE Resource Graph page: @{ Data; SkipToken; TotalRecords }. #>
|    param([string]$Query, [string[]]$Subscription, [string[]]$ManagementGroup, [int]$First = 1000, [int]$Skip = 0, [string]$SkipToken)
|    $opt = [ordered]@{ resultFormat = 'objectArray'; '$top' = $First }
|    if ($Skip -gt 0) { $opt['$skip'] = $Skip }
|    if ($SkipToken) { $opt['$skipToken'] = $SkipToken }
|    $body = [ordered]@{ query = $Query; options = $opt }
|    $subs = @(@($Subscription) | Where-Object { -not [string]::IsNullOrWhiteSpace([string]$_) })
|    $mgs  = @(@($ManagementGroup) | Where-Object { -not [string]::IsNullOrWhiteSpace([string]$_) })
|    if ($subs.Count) { $body['subscriptions'] = [string[]]$subs }
|    if ($mgs.Count) { $body['managementGroups'] = [string[]]$mgs }
|    $r = Invoke-SIAzRestRequest -Method POST -Uri 'https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01' `
|             -Body ($body | ConvertTo-Json -Depth 10 -Compress) -What 'Resource Graph query'
|    $j = $r.Content | ConvertFrom-Json
|    $tok = $null
|    if ($j.PSObject.Properties['$skipToken']) { $tok = [string]$j.'$skipToken' }
|    return [pscustomobject]@{ Data = @($j.data); SkipToken = $tok; TotalRecords = $j.totalRecords }
|}
|
|function Get-SIKeyVaultSecretValue {
|    <# One Key Vault secret as plain text; $null when the secret does not exist. #>
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$Name, [string]$Version, [hashtable]$Auth)
|    $j = Get-SIKeyVaultSecretRaw -VaultName $VaultName -Name $Name -Version $Version -Auth $Auth
|    if (-not $j) { return $null }
|    return [string]$j.value
|}
|
|function Get-SIKeyVaultSecretRaw {
|    param([string]$VaultName, [string]$Name, [string]$Version, [hashtable]$Auth)
|    $v = if ($Version) { '/' + $Version } else { '' }
|    $uri = 'https://{0}.vault.azure.net/secrets/{1}{2}?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name), $v
|    $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience KeyVault -AllowNotFound -Auth $Auth -What ("Key Vault secret '{0}' in '{1}'" -f $Name, $VaultName)
|    if (-not $r) { return $null }
|    return ($r.Content | ConvertFrom-Json)
|}
|
|function ConvertTo-SIAzLaCellString {
|    <# One Log Analytics cell, as Az.OperationalInsights hands it to callers: TEXT. Strings and dates stay as the
|       service sent them, numbers keep their JSON spelling, booleans are 'true' / 'false', null stays null, nested
|       values are JSON text. #>
|    param($Value)
|    if ($null -eq $Value) { return $null }
|    if ($Value -is [string]) { return $Value }
|    if ($Value -is [bool]) { if ($Value) { return 'true' } else { return 'false' } }
|    if ($Value -is [datetime]) { return $Value.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.FFFFFFFZ', [System.Globalization.CultureInfo]::InvariantCulture) }
|    if ($Value -is [System.IFormattable]) { return $Value.ToString($null, [System.Globalization.CultureInfo]::InvariantCulture) }
|    return (ConvertTo-Json -InputObject $Value -Depth 20 -Compress)
|}
|
|function ConvertFrom-SILaQueryJson {
|    <#
|        The Log Analytics query response -> @{ Tables = @( @{ Name; Columns = @(@{name;type}); Rows = @(@(cells as text)) } ); Error }.
|        pwsh 7: System.Text.Json, so a date stays the exact text the service sent (ConvertFrom-Json would turn it into a
|        local DateTime). Windows PowerShell 5.1: ConvertFrom-Json, which leaves dates as text.
|    #>
|    param([Parameter(Mandatory)][string]$Json)
|    $tables = [System.Collections.Generic.List[object]]::new()
|    $err = $null
|    if ($PSVersionTable.PSEdition -eq 'Core') {
|        $doc = [System.Text.Json.JsonDocument]::Parse($Json)
|        try {
|            $root = $doc.RootElement
|            $tEl = [System.Text.Json.JsonElement]::new()
|            if ($root.TryGetProperty('tables', [ref]$tEl)) {
|                foreach ($t in $tEl.EnumerateArray()) {
|                    $cols = [System.Collections.Generic.List[object]]::new()
|                    foreach ($c in $t.GetProperty('columns').EnumerateArray()) {
|                        $ty = [System.Text.Json.JsonElement]::new(); $tyS = ''
|                        if ($c.TryGetProperty('type', [ref]$ty)) { $tyS = $ty.GetString() }
|                        [void]$cols.Add([pscustomobject]@{ name = $c.GetProperty('name').GetString(); type = $tyS })
|                    }
|                    $rows = [System.Collections.Generic.List[object]]::new()
|                    foreach ($row in $t.GetProperty('rows').EnumerateArray()) {
|                        $cells = [System.Collections.Generic.List[object]]::new()
|                        foreach ($cell in $row.EnumerateArray()) {
|                            switch ($cell.ValueKind.ToString()) {
|                                'String' { [void]$cells.Add($cell.GetString()) }
|                                'Null'   { [void]$cells.Add($null) }
|                                'True'   { [void]$cells.Add('true') }
|                                'False'  { [void]$cells.Add('false') }
|                                default  { [void]$cells.Add($cell.GetRawText()) }
|                            }
|                        }
|                        [void]$rows.Add($cells.ToArray())
|                    }
|                    $nm = [System.Text.Json.JsonElement]::new(); $nmS = ''
|                    if ($t.TryGetProperty('name', [ref]$nm)) { $nmS = $nm.GetString() }
|                    [void]$tables.Add([pscustomobject]@{ Name = $nmS; Columns = $cols.ToArray(); Rows = $rows.ToArray() })
|                }
|            }
|            $eEl = [System.Text.Json.JsonElement]::new()
|            if ($root.TryGetProperty('error', [ref]$eEl) -and $eEl.ValueKind.ToString() -ne 'Null') { $err = ($eEl.GetRawText() | ConvertFrom-Json) }
|        } finally { $doc.Dispose() }
|    } else {
|        $j = $Json | ConvertFrom-Json
|        foreach ($t in @($j.tables)) {
|            if ($null -eq $t) { continue }
|            $rows = [System.Collections.Generic.List[object]]::new()
|            foreach ($row in @($t.rows)) {
|                $cells = [System.Collections.Generic.List[object]]::new()
|                foreach ($cell in @($row)) { [void]$cells.Add((ConvertTo-SIAzLaCellString $cell)) }
|                [void]$rows.Add($cells.ToArray())
|            }
|            [void]$tables.Add([pscustomobject]@{ Name = [string]$t.name; Columns = @($t.columns); Rows = $rows.ToArray() })
|        }
|        if ($j.PSObject.Properties['error'] -and $j.error) { $err = $j.error }
|    }
|    return [pscustomobject]@{ Tables = $tables.ToArray(); Error = $err }
|}
|
|function Get-SILaCompactRowType {
|    <#
|        #711. A .NET class for one column list: one public text property per column, in the column order, built from the
|        row's values in one call (new(string[])). Built once per column list and process (Add-Type, pwsh 7 / .NET 8) and
|        reused. $null when it cannot be built -- a column name that is not a plain identifier, two names that differ only in
|        case (PowerShell reads properties without case), Windows PowerShell -- and the caller keeps PSCustomObject rows.
|    #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    if ($PSVersionTable.PSEdition -ne 'Core' -or $Names.Count -eq 0) { return $null }
|    if ($null -eq $script:SILaCompactRowTypes) { $script:SILaCompactRowTypes = @{} }
|    $key = ($Names -join "`n")
|    if ($script:SILaCompactRowTypes.ContainsKey($key)) { return $script:SILaCompactRowTypes[$key] }
|    $type = $null
|    try {
|        $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
|        foreach ($n in $Names) { if ($n -notmatch '^[A-Za-z_][A-Za-z0-9_]*$' -or -not $seen.Add($n)) { throw ('not a plain column name: {0}' -f $n) } }
|        $sha = [System.Security.Cryptography.SHA256]::Create()
|        try { $h = ([System.BitConverter]::ToString($sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($key))) -replace '-', '').Substring(0, 20) } finally { $sha.Dispose() }
|        $cls = 'R' + $h
|        $full = 'SecurityInsight.LaRows.' + $cls
|        $type = $full -as [type]
|        if ($null -eq $type) {
|            $sb = New-Object System.Text.StringBuilder
|            [void]$sb.Append('namespace SecurityInsight.LaRows { public sealed class ').Append($cls).Append(' { ')
|            foreach ($n in $Names) { [void]$sb.Append('public string @').Append($n).Append(' { get; set; } ') }
|            [void]$sb.Append('public ').Append($cls).Append('(string[] v) { ')
|            for ($i = 0; $i -lt $Names.Count; $i++) { [void]$sb.Append('this.@').Append($Names[$i]).Append(' = v[').Append($i).Append(']; ') }
|            [void]$sb.Append('} } }')
|            Add-Type -TypeDefinition $sb.ToString() -Language CSharp -ErrorAction Stop
|            $type = $full -as [type]
|        }
|    } catch { $type = $null }
|    $script:SILaCompactRowTypes[$key] = $type
|    return $type
|}
|
|function ConvertFrom-SILaQueryRows {
|    <#
|        The Log Analytics query response AS THE BYTES THE SERVICE SENT -> @{ Rows; Error }: the primary table's rows, one
|        object per row, one TEXT property per column -- the same rows Invoke-SILaQuery hands out as .Results.
|        For large answers (Invoke-SILaQuery -RowsOnly): the bytes are parsed where they are. The answer is never also held
|        as one text (twice its size), as a second copy of every table, or as a list of cells per row -- on a large install
|        those copies together ran a job out of memory. pwsh 7 only (System.Text.Json).
|    #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][byte[]]$Bytes)
|    $rows = [System.Collections.Generic.List[object]]::new()
|    $cols = [System.Collections.Generic.List[object]]::new()
|    $err = $null
|    $doc = [System.Text.Json.JsonDocument]::Parse([System.ReadOnlyMemory[byte]]::new($Bytes))
|    try {
|        $root = $doc.RootElement
|        $tEl = [System.Text.Json.JsonElement]::new()
|        if ($root.TryGetProperty('tables', [ref]$tEl)) {
|            # the table named PrimaryResult, else the first one -- as .Results has always been chosen
|            $have = $false
|            $pick = [System.Text.Json.JsonElement]::new()
|            foreach ($t in $tEl.EnumerateArray()) {
|                $nm = [System.Text.Json.JsonElement]::new(); $nmS = ''
|                if ($t.TryGetProperty('name', [ref]$nm)) { $nmS = [string]$nm.GetString() }
|                if (-not $have) { $pick = $t; $have = $true }
|                if ($nmS -eq 'PrimaryResult') { $pick = $t; break }
|            }
|            if ($have) {
|                $names = [System.Collections.Generic.List[string]]::new()
|                foreach ($c in $pick.GetProperty('columns').EnumerateArray()) {
|                    $names.Add([string]$c.GetProperty('name').GetString())
|                    $ty = [System.Text.Json.JsonElement]::new(); $tyS = $null
|                    if ($c.TryGetProperty('type', [ref]$ty)) { $tyS = $ty.GetString() }
|                    $cols.Add([pscustomobject]@{ name = $names[$names.Count - 1]; type = $tyS })
|                }
|                $nCols = $names.Count
|                # #711: a caller that keeps the rows for long (Risk Analysis' lookups) asks for COMPACT rows -- one small
|                # .NET object per row with one text property per column (Get-SILaCompactRowType), not a PSCustomObject
|                # (measured on the test VM: ~6 KB per row of 11 columns as a PSCustomObject). Read the same way by
|                # every reader ($row.Col, $row.PSObject.Properties['Col'].Value). Not available -> the rows as always.
|                $compactType = $null
|                if ([bool]$global:SI_LaCompactRows) { $compactType = Get-SILaCompactRowType -Names $names.ToArray() }
|                if ($null -ne $compactType) {
|                    # a short value that repeats (a tier, a flag, an empty text, a short factor list) is held once per read
|                    $pool = [System.Collections.Generic.Dictionary[string, string]]::new([System.StringComparer]::Ordinal)
|                    foreach ($row in $pick.GetProperty('rows').EnumerateArray()) {
|                        # a null cell is left as the array's own null (assigning $null to a [string] element would make it '')
|                        $vals = [string[]]::new($nCols)
|                        $i = 0
|                        foreach ($cell in $row.EnumerateArray()) {
|                            if ($i -ge $nCols) { break }
|                            $kind = $cell.ValueKind.ToString()
|                            if ($kind -ne 'Null') {
|                                $s = if ($kind -eq 'String') { $cell.GetString() } elseif ($kind -eq 'True') { 'true' } elseif ($kind -eq 'False') { 'false' } else { $cell.GetRawText() }
|                                if ($s.Length -le 32) { $p0 = $null; if ($pool.TryGetValue($s, [ref]$p0)) { $s = $p0 } else { $pool[$s] = $s } }
|                                $vals[$i] = $s
|                            }
|                            $i++
|                        }
|                        [void]$rows.Add($compactType::new($vals))
|                    }
|                    $nCols = -1
|                }
|                if ($nCols -ge 0) {
|                foreach ($row in $pick.GetProperty('rows').EnumerateArray()) {
|                    $o = [ordered]@{}
|                    $i = 0
|                    foreach ($cell in $row.EnumerateArray()) {
|                        if ($i -ge $nCols) { break }
|                        $name = $names[$i]
|                        $kind = $cell.ValueKind.ToString()
|                        if ($kind -eq 'String') { $o[$name] = $cell.GetString() }
|                        elseif ($kind -eq 'Null') { $o[$name] = $null }
|                        elseif ($kind -eq 'True') { $o[$name] = 'true' }
|                        elseif ($kind -eq 'False') { $o[$name] = 'false' }
|                        else { $o[$name] = $cell.GetRawText() }
|                        $i++
|                    }
|                    # a row shorter than its columns: the missing ones are empty, as before
|                    for (; $i -lt $nCols; $i++) { $o[$names[$i]] = $null }
|                    [void]$rows.Add([pscustomobject]$o)
|                }
|                }
|            }
|        }
|        $eEl = [System.Text.Json.JsonElement]::new()
|        if ($root.TryGetProperty('error', [ref]$eEl) -and $eEl.ValueKind.ToString() -ne 'Null') { $err = ($eEl.GetRawText() | ConvertFrom-Json) }
|    } finally { $doc.Dispose() }
|    return [pscustomobject]@{ Rows = $rows.ToArray(); Columns = $cols.ToArray(); Error = $err }
|}
|
|function Get-SILaServiceRowLimit {
|    <# The most rows ONE Log Analytics query answer carries (the service's own limit). An answer holding exactly that many
|       rows cannot be told from an answer the service cut there. $global:SI_LaServiceRowLimit overrides it (tests). #>
|    $v = 0L
|    try { $v = [long]$global:SI_LaServiceRowLimit } catch { $v = 0L }
|    if ($v -gt 0) { return $v }
|    return 500000L
|}
|
|function Get-SILaPartialVerdict {
|    <#
|        PURE. What a Log Analytics partial answer (the "error" object beside the rows of an HTTP 200 answer) says, read from
|        its LEAVES (the innermost error objects -- the outer ones are generic). Returns @{ Kind; Code; Detail; Tables }:
|          Unresolved  every leaf is "Failed to resolve table or column expression named 'SI_..._CL'": a `union isfuzzy=true`
|                      leg over a SecurityInsight table this workspace does not have yet. The answer IS the whole result (the
|                      missing table has no rows) -- the one partial answer that is not a cut one.
|          Limit       a leaf names a limit (rows / size / time / memory): the answer is CUT; a smaller read fixes it.
|          Other       anything else: the answer is short, and a smaller read does not fix it.
|        The same reading as Risk Analysis' own (RA-LaPartedRead.ps1 Get-RALaPartialVerdict); kept here so every reader of
|        Log Analytics refuses a cut answer, not only Risk Analysis.
|        -MayBeMissing (2026-10-23): other tables the CALLER names that this workspace may not have (the capability probe's
|        SecurityIncident / SecurityAlert in a workspace without Sentinel): a leaf that cannot resolve one of them is
|        Unresolved too -- the answer is whole, the table has no rows. Only the tables named; never any other.
|    #>
|    param([AllowNull()][object]$ErrorObject, [string[]]$MayBeMissing = @())
|    $leaves = New-Object System.Collections.Generic.List[string]
|    $all = New-Object System.Collections.Generic.List[string]
|    $codes = New-Object System.Collections.Generic.List[string]
|    $get = {
|        param($o, $n)
|        if ($null -eq $o) { return $null }
|        if ($o -is [System.Collections.IDictionary]) { if ($o.Contains($n)) { return $o[$n] }; return $null }
|        $p = $o.PSObject.Properties[$n]; if ($p) { return $p.Value }; return $null
|    }
|    $stack = New-Object System.Collections.Stack
|    if ($null -ne $ErrorObject -and $ErrorObject -isnot [string]) { $stack.Push($ErrorObject) }
|    $visited = 0
|    while ($stack.Count -gt 0 -and $visited -lt 256) {
|        $o = $stack.Pop(); $visited++
|        if ($null -eq $o -or $o -is [string]) { continue }
|        $m = [string](& $get $o 'message'); $c = [string](& $get $o 'code')
|        if ($c -and $codes.Count -lt 3 -and -not $codes.Contains($c)) { $codes.Add($c) }
|        if ($m) { $all.Add($m) }
|        $children = New-Object System.Collections.Generic.List[object]
|        $ie = & $get $o 'innererror'; if ($null -ne $ie -and $ie -isnot [string]) { $children.Add($ie) }
|        $ds = & $get $o 'details'
|        if ($null -ne $ds) { foreach ($d in @($ds)) { if ($null -ne $d -and $d -isnot [string]) { $children.Add($d) } } }
|        if ($children.Count -eq 0) { if ($m) { $leaves.Add($m) } }
|        else { for ($i = $children.Count - 1; $i -ge 0; $i--) { $stack.Push($children[$i]) } }
|    }
|    if ($null -ne $ErrorObject -and $ErrorObject -is [string]) { $leaves.Add([string]$ErrorObject); $all.Add([string]$ErrorObject) }
|    $generic = '^(There were some errors when processing your query\.?|Something went wrong processing your query on the server\.?)$'
|    $specific = @($all | Where-Object { $_ -notmatch $generic } | Select-Object -Unique)
|    $detail = (@($specific) -join '; ')
|    if (-not $detail) { $detail = (@($all | Select-Object -Unique) -join '; ') }
|    if ($detail.Length -gt 400) { $detail = $detail.Substring(0, 400) + '...' }
|    $code = (@($codes) -join '/')
|    # a 'union' leaf says "table expression", a 'where' leaf "table or column expression" (both: the table is not there)
|    $rx = "Failed to resolve table (?:or column )?expression named '(?<t>[A-Za-z0-9_]+)'"
|    $okMissing = { param($t) ($t -match '^SI_[A-Za-z0-9_]+_CL$') -or (@($MayBeMissing | Where-Object { $_ -and [string]$_ -ieq $t }).Count -gt 0) }
|    $tables = New-Object System.Collections.Generic.List[string]
|    $leafSpecific = @($leaves | Where-Object { $_ -notmatch $generic })
|    $allResolve = ($leafSpecific.Count -gt 0)
|    foreach ($l in $leafSpecific) {
|        $mm = [regex]::Match($l, $rx)
|        if (-not $mm.Success -or -not (& $okMissing $mm.Groups['t'].Value)) { $allResolve = $false; break }
|        if (-not $tables.Contains($mm.Groups['t'].Value)) { $tables.Add($mm.Groups['t'].Value) }
|    }
|    if ($allResolve) { return @{ Kind = 'Unresolved'; Code = $code; Detail = $detail; Tables = $tables.ToArray() } }
|    $limitRx = '(?i)limit|exceeded|too large|E_QUERY_RESULT_SET_TOO_LARGE|timed out|timeout|E_RUNAWAY|out of memory|memory|truncat|cancell?ed|preempted'
|    if (@($all | Where-Object { $_ -match $limitRx }).Count -gt 0) { return @{ Kind = 'Limit'; Code = $code; Detail = $detail; Tables = @() } }
|    return @{ Kind = 'Other'; Code = $code; Detail = $detail; Tables = @() }
|}
|
|function Test-SILaAnswerWhole {
|    <#
|        PURE. Is a Log Analytics answer the WHOLE result? -ErrorObject: the partial-error object beside the rows; -Rows: how
|        many rows the answer held. Returns @{ Whole; Kind; Code; Detail; Tables; Rows }:
|          no error and fewer rows than the service's own row limit   -> whole
|          an Unresolved partial error (a missing SI table in a fuzzy union)  -> whole (the missing table has no rows)
|          a Limit / Other partial error                              -> NOT whole
|          no error, but exactly as many rows as the service's limit  -> NOT whole (Limit): it cannot be told from a cut answer
|    #>
|    # -MayBeMissing: as Get-SILaPartialVerdict (the tables the caller names that the workspace may not have)
|    param([AllowNull()][object]$ErrorObject, [long]$Rows = 0, [string[]]$MayBeMissing = @())
|    if ($null -ne $ErrorObject) {
|        $v = Get-SILaPartialVerdict -ErrorObject $ErrorObject -MayBeMissing $MayBeMissing
|        return @{ Whole = ($v.Kind -eq 'Unresolved'); Kind = $v.Kind; Code = $v.Code; Detail = $v.Detail; Tables = $v.Tables; Rows = $Rows }
|    }
|    $cap = Get-SILaServiceRowLimit
|    if ($Rows -ge $cap) {
|        $d = [string]::Format([System.Globalization.CultureInfo]::InvariantCulture, 'the answer holds {0:N0} rows, the most one answer carries (the service''s limit of {1:N0} rows) -- it cannot be told from a cut answer', $Rows, $cap)
|        return @{ Whole = $false; Kind = 'Limit'; Code = 'RowLimit'; Detail = $d; Tables = @(); Rows = $Rows }
|    }
|    return @{ Whole = $true; Kind = ''; Code = ''; Detail = ''; Tables = @(); Rows = $Rows }
|}
|
|function New-SILaCutAnswerError {
|    <#
|        The error a refused cut answer becomes (Invoke-SILaQuery without -AllowPartial). An ErrorRecord whose exception
|        carries the service's own words three ways, so every classifier that reads a failed query finds them:
|          * the message: "Log Analytics returned a PARTIAL answer (<code>: <detail>) -- ..."; a Limit also says "Query
|            execution has exceeded the allowed limits" (the text Risk Analysis' bucket logic makes a slice smaller on);
|          * Exception.Response.Content and ErrorDetails: the error object as JSON (Get-SIKqlErrorText -> the data sync's
|            "too large" check, Test-SIDataResponseTooLarge, cuts that page in two);
|          * Exception.Data: SILaPartial / SIRALaPartial = the kind, SIRALaPartialRows = the rows the short answer held (Risk
|            Analysis' parted reader measures with them).
|    #>
|    param([Parameter(Mandatory)][hashtable]$Verdict, [AllowNull()][object]$ErrorObject, [string]$WorkspaceId = '')
|    $msg = if ($Verdict.Kind -eq 'Limit') {
|        "Log Analytics returned a PARTIAL answer ({0}: {1}) -- Query execution has exceeded the allowed limits; the rows it returned are not the whole result and were not used" -f $Verdict.Code, $Verdict.Detail
|    } else {
|        "Log Analytics returned a PARTIAL answer ({0}: {1}) -- the rows it returned are not the whole result and were not used" -f $Verdict.Code, $Verdict.Detail
|    }
|    $json = ''
|    if ($null -ne $ErrorObject) { try { $json = ConvertTo-Json -InputObject ([pscustomobject]@{ error = $ErrorObject }) -Depth 12 -Compress } catch { $json = [string]$ErrorObject } }
|    else { $json = ConvertTo-Json -InputObject ([pscustomobject]@{ error = [pscustomobject]@{ code = [string]$Verdict.Code; message = [string]$Verdict.Detail } }) -Depth 4 -Compress }
|    $ex = New-SIAzRestError -Message $msg -Response ([pscustomobject]@{ StatusCode = 200; Content = $json; Headers = @{} })
|    $ex.Data['SILaPartial'] = [string]$Verdict.Kind
|    $ex.Data['SIRALaPartial'] = [string]$Verdict.Kind
|    $ex.Data['SIRALaPartialRows'] = [long]$Verdict.Rows
|    $er = New-Object System.Management.Automation.ErrorRecord($ex, 'SILaQueryPartial', [System.Management.Automation.ErrorCategory]::LimitsExceeded, $WorkspaceId)
|    $er.ErrorDetails = New-Object System.Management.Automation.ErrorDetails($json)
|    return $er
|}
|
|function Test-SILaCutAnswerError {
|    <# PURE. Was this failure a cut answer Invoke-SILaQuery refused (New-SILaCutAnswerError)? -Kind: only that kind. #>
|    param([AllowNull()][object]$Err, [string]$Kind = '')
|    $ex = $null
|    if ($Err -is [System.Management.Automation.ErrorRecord]) { $ex = $Err.Exception } elseif ($Err -is [System.Exception]) { $ex = $Err }
|    while ($null -ne $ex) {
|        if ($ex.Data -and $ex.Data.Contains('SILaPartial')) { return ((-not $Kind) -or ([string]$ex.Data['SILaPartial'] -eq $Kind)) }
|        $ex = $ex.InnerException
|    }
|    return $false
|}
|
|function Invoke-SILaQuery {
|    <#
|        A KQL query on the Log Analytics DATA PLANE: POST https://api.loganalytics.io/v1/workspaces/{id}/query. Not the
|        ARM /api/query route, which hides the semantic error behind a generic one.
|        Returns the shape Invoke-AzOperationalInsightsQuery returns and every caller reads:
|            .Results   the primary table's rows, one object per row, one TEXT property per column (as Az hands them)
|            .Columns   the primary table's columns (name / type) -- what the workbooks type their columns from
|            .Tables    ONE entry: the primary table's Name and Columns, NO rows (RowsOmitted). The rows are in .Results only;
|                       the answer is never held a second time as tables beside them (#639). No caller reads table rows.
|            .Error     the partial-error object (or $null) -- only ever set beside rows that ARE the whole result (a missing SI
|                       table in a fuzzy union), or with -AllowPartial
|            .RowCount  the rows the answer held (with -OnPage: the rows handed to it)
|        A CUT ANSWER IS REFUSED (#639, working rule 4). Log Analytics answers HTTP 200 with the rows it got to AND an error
|        object when it stopped early (a result over its row / size limit, a part that timed out); an answer with exactly as
|        many rows as the service's own row limit cannot be told from one cut there. Such an answer THROWS
|        (New-SILaCutAnswerError: the service's words, the kind, the rows it held) -- a cut answer is never handed out as
|        whole. -AllowPartial: the caller reads .Error itself and decides (the rows and the error come back as before, and
|        .Partial says the kind). A read that pages (its query keys the rows) catches the "too large" refusal and reads that
|        page again in smaller pages -- the refusal carries the same words the cut answer did.
|        -OnPage { param($Rows) }: the rows are handed on a PAGE at a time as they arrive (about -PageBytes of answer each,
|        the size measured from the answer's own bytes) and never collected -- memory is one page, whatever the size of the
|        answer. .Results is then empty. The pages are PROVISIONAL until this call returns: a cut answer (said at the END of
|        the answer) or a read that fails half-way throws AFTER pages were handed on, so a caller stages the pages and keeps
|        them only when the call returned. Without the streaming reader (Windows PowerShell, or it cannot be built) the
|        answer is read the older way and then handed on in pages of the same size.
|        THE LEAN READ IS THE DEFAULT (#639): on pwsh 7 the answer arrives as bytes and its rows are read from those bytes
|        (ConvertFrom-SILaQueryRows) -- never also held as one text (twice its size) or as a list of cells per row. The same
|        rows and the same text values as before. Windows PowerShell (no System.Text.Json) reads the text, as always.
|        -WorkspaceId is the workspace's customer id (GUID). -Wait = server timeout in seconds (Prefer: wait=N).
|        -RowsOnly is kept for the callers that name it; it is what every read does now.
|        A refused query throws with the service's own code and message, e.g.
|            "Operation returned an invalid status code 'BadRequest' -- BadArgumentError/SemanticError/SEM0100: ..."
|        and carries the body in Exception.Response.Content and ErrorDetails -- what SI-KqlError.ps1 reads.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$WorkspaceId,
|        [Parameter(Mandatory)][string]$Query,
|        [int]$Wait = 0,
|        [timespan]$Timespan = [timespan]::Zero,
|        [int]$MaxAttempts = 4,
|        [switch]$RowsOnly,
|        # the caller reads .Error itself and decides what a cut answer means (never the default)
|        [switch]$AllowPartial,
|        # the rows a page at a time, never collected (see above)
|        [scriptblock]$OnPage,
|        [long]$PageBytes = 4MB
|    )
|    Initialize-SIAzRestHelpers
|    if ($OnPage) {
|        return (Invoke-SILaQueryPaged -WorkspaceId $WorkspaceId -Query $Query -Wait $Wait -Timespan $Timespan -MaxAttempts $MaxAttempts -AllowPartial:$AllowPartial -OnPage $OnPage -PageBytes $PageBytes)
|    }
|    $uri = 'https://api.loganalytics.io/v1/workspaces/{0}/query' -f $WorkspaceId.Trim()
|    $body = [ordered]@{ query = $Query }
|    if ($Timespan -gt [timespan]::Zero) { $body['timespan'] = [System.Xml.XmlConvert]::ToString($Timespan) }
|    $headers = @{}
|    $timeout = 300
|    # #882 (A4): Log Analytics stops a query at 3 minutes unless asked to wait -- every query asks for its maximum (10 minutes)
|    if ($Wait -le 0) { $Wait = 600 }
|    if ($Wait -gt 0) { $headers['Prefer'] = ('wait={0}' -f $Wait); $timeout = $Wait + 60 }
|    # the answer as bytes wherever it can be read from them (pwsh 7) -- the lean read is the default (#639)
|    $asBytes = ([bool]$RowsOnly -or $PSVersionTable.PSEdition -eq 'Core')
|    # #730: Risk Analysis' reads (its lookups -- SI_LaCompactRows -- and its Log Analytics answers -- SI_LaStreamRows) are
|    # read AS THEY ARRIVE (SI-LaStreamRead.ps1): the same rows, the answer never held whole. Everything else reads as before.
|    $readStream = $null
|    if ($PSVersionTable.PSEdition -eq 'Core' -and ([bool]$global:SI_LaCompactRows -or [bool]$global:SI_LaStreamRows) -and
|        (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore)) {
|        if (Get-SILaStreamReaderType) {
|            $__lsCompact = [bool]$global:SI_LaCompactRows
|            # (no closure: it runs inside this call, so $__lsCompact is seen; a closure would not see this file's functions)
|            # #836: a failed stream read answers a marker -- read again below the older way, never an error of the query
|            $readStream = { param($s) Read-SILaQueryStreamSafe -Stream $s -Compact:$__lsCompact }
|        } else {
|            # #836: never silent -- one line on the run log says the older read is used and why
|            Write-SILaStreamFallback -Once -Reason ([string]$global:SI_LaStreamReaderOff)
|        }
|    }
|    $rq = @{ Method = 'POST'; Uri = $uri; Audience = 'LaQuery'; Body = ($body | ConvertTo-Json -Compress -Depth 5); Headers = $headers
|             TimeoutSec = $timeout; MaxAttempts = $MaxAttempts; AllowStatus = @(400, 403, 404, 409, 413, 422); What = 'Log Analytics query'; AsBytes = $asBytes }
|    if ($readStream) { $rq['ReadStream'] = $readStream }
|    $r = Invoke-SIAzRestRequest @rq
|    if ($readStream -and $r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and $r.Parsed.PSObject.Properties['SILaStreamFailed']) {
|        # #836: the stream read of this answer failed -- the same query again, read the older way (data first), and said
|        Write-SILaStreamFallback -Reason ('reading this answer as it arrived failed (' + [string]$r.Parsed.SILaStreamFailed + '), so it was read again')
|        $r = $null
|        [void]$rq.Remove('ReadStream')
|        $r = Invoke-SIAzRestRequest @rq
|    }
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and [int]$r.StatusCode -lt 400) {
|        $streamed = $r.Parsed
|        $r = $null
|        return (Complete-SILaQueryAnswer -Results $streamed.Rows -Columns $streamed.Columns -QueryError $streamed.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|    }
|    $code = [int]$r.StatusCode
|    # A refusal (always small) is read as text, as is every answer on Windows PowerShell (no System.Text.Json there); an
|    # answer on pwsh 7 is parsed from its bytes below.
|    $content = [string]$r.Content
|    $hasBytes = ($asBytes -and $null -ne $r.Bytes -and $r.Bytes.Length -gt 0)
|    $lean = ($hasBytes -and $code -lt 400 -and $PSVersionTable.PSEdition -eq 'Core')
|    if ($hasBytes -and -not $lean) { $content = [System.Text.Encoding]::UTF8.GetString($r.Bytes) }
|    if ($code -ge 400) { throw (New-SILaQueryRefusedError -Code $code -Content $content -Headers $r.Headers -WorkspaceId $WorkspaceId) }
|    if ($lean) {
|        # a plain statement, never through $( ... ): a subexpression would enumerate the byte array into object[]
|        [byte[]]$answer = $r.Bytes
|        $r = $null
|        $leanAnswer = ConvertFrom-SILaQueryRows -Bytes $answer
|        $answer = $null
|        return (Complete-SILaQueryAnswer -Results $leanAnswer.Rows -Columns $leanAnswer.Columns -QueryError $leanAnswer.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|    }
|    $parsed = ConvertFrom-SILaQueryJson -Json $content
|    $content = $null
|    $results = [System.Collections.Generic.List[object]]::new()
|    $first = @($parsed.Tables | Where-Object { $_.Name -eq 'PrimaryResult' }) + @($parsed.Tables) | Select-Object -First 1
|    $cols = @()
|    if ($first) {
|        $names = @($first.Columns | ForEach-Object { [string]$_.name })
|        $cols = @($first.Columns | ForEach-Object { [pscustomobject]@{ name = [string]$_.name; type = $(if ($_.PSObject.Properties['type']) { [string]$_.type } else { $null }) } })
|        foreach ($row in $first.Rows) {
|            $o = [ordered]@{}
|            for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = $row[$i] }
|            [void]$results.Add([pscustomobject]$o)
|        }
|    }
|    $err = $parsed.Error
|    $parsed = $null; $first = $null
|    return (Complete-SILaQueryAnswer -Results $results.ToArray() -Columns $cols -QueryError $err -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|}
|
|function New-SILaQueryRefusedError {
|    <# The error a refused query (HTTP 4xx) becomes: the service's own code and message, the body for SI-KqlError. #>
|    param([int]$Code, [AllowNull()][AllowEmptyString()][string]$Content, $Headers, [string]$WorkspaceId = '')
|    $base = "Operation returned an invalid status code '{0}'" -f (Get-SIAzRestStatusName $Code)
|    $resp = [pscustomobject]@{ StatusCode = $Code; Content = $Content; Headers = $Headers }
|    $probe = New-SIAzRestError -Message $base -Response $resp
|    $msg = Get-SIKqlErrorSummary -ErrorRecord $probe
|    if ($msg -eq $base) {
|        # no innererror chain: the top-level error code + message
|        try { $e = ($Content | ConvertFrom-Json).error; if ($e) { $msg = ('{0} -- {1}: {2}' -f $base, [string]$e.code, [string]$e.message) } } catch { }
|    }
|    $ex = New-SIAzRestError -Message $msg -Response $resp
|    $er = New-Object System.Management.Automation.ErrorRecord($ex, 'SILaQueryFailed', [System.Management.Automation.ErrorCategory]::InvalidOperation, $WorkspaceId)
|    $er.ErrorDetails = New-Object System.Management.Automation.ErrorDetails($Content)
|    $er
|}
|
|function Complete-SILaQueryAnswer {
|    <#
|        The end of every Invoke-SILaQuery read: a cut answer (Test-SILaAnswerWhole) THROWS (New-SILaCutAnswerError) unless
|        -AllowPartial; otherwise the answer (New-SILaQueryAnswer), with .Partial = the kind of a partial answer handed out
|        under -AllowPartial ('' when whole).
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Results = @(), [AllowNull()][AllowEmptyCollection()][object[]]$Columns = @(), $QueryError,
|          [switch]$AllowPartial, [string]$WorkspaceId = '', [long]$RowCount = -1)
|    $n = $RowCount
|    if ($n -lt 0) { $n = 0L; if ($null -ne $Results) { $n = [long]$Results.Count } }
|    $v = Test-SILaAnswerWhole -ErrorObject $QueryError -Rows $n
|    if (-not $v.Whole -and -not $AllowPartial) { throw (New-SILaCutAnswerError -Verdict $v -ErrorObject $QueryError -WorkspaceId $WorkspaceId) }
|    $a = New-SILaQueryAnswer -Results $Results -Columns $Columns -QueryError $QueryError
|    $kind = ''; if (-not $v.Whole) { $kind = [string]$v.Kind }
|    $a | Add-Member -NotePropertyName Partial -NotePropertyValue $kind -Force
|    $a | Add-Member -NotePropertyName RowCount -NotePropertyValue $n -Force
|    $a
|}
|
|function Invoke-SILaQueryPaged {
|    <#
|        Invoke-SILaQuery -OnPage: the rows handed on a page at a time, never collected (see Invoke-SILaQuery). The streaming
|        reader (SI-LaStreamRead.ps1) delivers each page as soon as about -PageBytes of the answer's own bytes are in; the
|        compact rows of $global:SI_LaCompactRows apply. A cut answer is refused at the end, after the pages (they are
|        provisional until this returns). A stream read that fails BEFORE any page was handed on is read again the older way;
|        one that fails AFTER a page was handed on throws (handing the pages on again would hand some rows twice).
|        Without the streaming reader: the older read, then the rows in pages of the same measured size.
|        Returns the answer shape with no rows in .Results; .RowCount = the rows handed on, .Pages = the pages.
|    #>
|    param([Parameter(Mandatory)][string]$WorkspaceId, [Parameter(Mandatory)][string]$Query, [int]$Wait = 0,
|          [timespan]$Timespan = [timespan]::Zero, [int]$MaxAttempts = 4, [switch]$AllowPartial,
|          [Parameter(Mandatory)][scriptblock]$OnPage, [long]$PageBytes = 4MB)
|    if ($PageBytes -lt 1KB) { $PageBytes = 1KB }
|    $uri = 'https://api.loganalytics.io/v1/workspaces/{0}/query' -f $WorkspaceId.Trim()
|    $body = [ordered]@{ query = $Query }
|    if ($Timespan -gt [timespan]::Zero) { $body['timespan'] = [System.Xml.XmlConvert]::ToString($Timespan) }
|    $headers = @{}
|    $timeout = 300
|    # #882 (A4): Log Analytics stops a query at 3 minutes unless asked to wait -- every query asks for its maximum (10 minutes)
|    if ($Wait -le 0) { $Wait = 600 }
|    if ($Wait -gt 0) { $headers['Prefer'] = ('wait={0}' -f $Wait); $timeout = $Wait + 60 }
|    $rq = @{ Method = 'POST'; Uri = $uri; Audience = 'LaQuery'; Body = ($body | ConvertTo-Json -Compress -Depth 5); Headers = $headers
|             TimeoutSec = $timeout; MaxAttempts = $MaxAttempts; AllowStatus = @(400, 403, 404, 409, 413, 422); What = 'Log Analytics query'
|             AsBytes = ($PSVersionTable.PSEdition -eq 'Core') }
|    $streamable = ($PSVersionTable.PSEdition -eq 'Core' -and (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore) -and (Get-SILaStreamReaderType))
|    $state = @{ Pages = 0; Rows = 0L }
|    if ($streamable) {
|        $__lpCompact = [bool]$global:SI_LaCompactRows
|        $__lpOn = $OnPage; $__lpBytes = $PageBytes; $__lpState = $state
|        $rq['ReadStream'] = { param($s) Read-SILaQueryStreamSafe -Stream $s -Compact:$__lpCompact -OnPage $__lpOn -PageBytes $__lpBytes -PageState $__lpState }
|    } elseif ($PSVersionTable.PSEdition -eq 'Core') {
|        Write-SILaStreamFallback -Once -Reason ([string]$global:SI_LaStreamReaderOff)
|    }
|    $r = Invoke-SIAzRestRequest @rq
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and $r.Parsed.PSObject.Properties['SILaStreamFailed']) {
|        if ([int]$state.Pages -gt 0) {
|            throw ('Log Analytics: the answer could not be read to its end ({0}) after {1} page(s) had been handed on -- the read is not whole and its pages must not be used' -f [string]$r.Parsed.SILaStreamFailed, $state.Pages)
|        }
|        Write-SILaStreamFallback -Reason ('reading this answer as it arrived failed (' + [string]$r.Parsed.SILaStreamFailed + '), so it was read again')
|        $r = $null
|        [void]$rq.Remove('ReadStream')
|        $r = Invoke-SIAzRestRequest @rq
|    }
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and [int]$r.StatusCode -lt 400) {
|        $p = $r.Parsed; $r = $null
|        $a = Complete-SILaQueryAnswer -Results @() -Columns $p.Columns -QueryError $p.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId -RowCount ([long]$p.RowCount)
|        $a | Add-Member -NotePropertyName Pages -NotePropertyValue ([int]$p.Pages) -Force
|        return $a
|    }
|    # the older read (no streaming reader, or read again): the same refusal of a 4xx and of a cut answer, then the pages
|    [void]$rq.Remove('ReadStream')
|    if ($null -eq $r) { $r = Invoke-SIAzRestRequest @rq }
|    $code = [int]$r.StatusCode
|    $content = [string]$r.Content
|    if ($null -ne $r.Bytes -and $r.Bytes.Length -gt 0 -and ($code -ge 400 -or $PSVersionTable.PSEdition -ne 'Core')) { $content = [System.Text.Encoding]::UTF8.GetString($r.Bytes) }
|    if ($code -ge 400) { throw (New-SILaQueryRefusedError -Code $code -Content $content -Headers $r.Headers -WorkspaceId $WorkspaceId) }
|    $lean = $null
|    if ($null -ne $r.Bytes -and $r.Bytes.Length -gt 0 -and $PSVersionTable.PSEdition -eq 'Core') {
|        [byte[]]$bytes = $r.Bytes
|        $total = [long]$bytes.Length
|        $r = $null
|        $lean = ConvertFrom-SILaQueryRows -Bytes $bytes
|        $bytes = $null
|    } else {
|        $total = [long][System.Text.Encoding]::UTF8.GetByteCount($content)
|        $parsed = ConvertFrom-SILaQueryJson -Json $content
|        $content = $null
|        $first = @($parsed.Tables | Where-Object { $_.Name -eq 'PrimaryResult' }) + @($parsed.Tables) | Select-Object -First 1
|        $rowsL = [System.Collections.Generic.List[object]]::new(); $colsL = @()
|        if ($first) {
|            $names = @($first.Columns | ForEach-Object { [string]$_.name })
|            $colsL = @($first.Columns | ForEach-Object { [pscustomobject]@{ name = [string]$_.name; type = $(if ($_.PSObject.Properties['type']) { [string]$_.type } else { $null }) } })
|            foreach ($row in $first.Rows) { $o = [ordered]@{}; for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = $row[$i] }; [void]$rowsL.Add([pscustomobject]$o) }
|        }
|        $lean = [pscustomobject]@{ Rows = $rowsL.ToArray(); Columns = $colsL; Error = $parsed.Error }
|        $parsed = $null; $first = $null
|    }
|    $all = @($lean.Rows); $n = $all.Count
|    # a cut answer is refused BEFORE a page is handed on (the whole answer is in hand on this path)
|    $v = Test-SILaAnswerWhole -ErrorObject $lean.Error -Rows $n
|    if (-not $v.Whole -and -not $AllowPartial) { throw (New-SILaCutAnswerError -Verdict $v -ErrorObject $lean.Error -WorkspaceId $WorkspaceId) }
|    # pages of about -PageBytes of the answer: the measured bytes per row of this answer decide the rows per page
|    $per = $n
|    if ($n -gt 0 -and $total -gt $PageBytes) { $per = [int][Math]::Max(1, [Math]::Floor($n * ([double]$PageBytes / [double]$total))) }
|    $pages = 0
|    for ($i = 0; $i -lt $n; $i += [Math]::Max(1, $per)) {
|        $len = [Math]::Min([Math]::Max(1, $per), $n - $i)
|        $pg = [object[]]::new($len); [Array]::Copy($all, $i, $pg, 0, $len)
|        $null = & $OnPage $pg
|        $pages++
|        for ($k = $i; $k -lt $i + $len; $k++) { $all[$k] = $null }
|    }
|    $a = Complete-SILaQueryAnswer -Results @() -Columns $lean.Columns -QueryError $lean.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId -RowCount ([long]$n)
|    $a | Add-Member -NotePropertyName Pages -NotePropertyValue $pages -Force
|    $a
|}
|
|function New-SILaQueryAnswer {
|    <#
|        PURE. The one shape Invoke-SILaQuery answers (#639): .Results (the rows), .Columns (name / type), .Tables = the
|        primary table's SCHEMA only (Name, Columns, no rows -- RowsOmitted), .Error. The rows are never held twice.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Results = @(), [AllowNull()][AllowEmptyCollection()][object[]]$Columns = @(), $QueryError)
|    $c = @($Columns | Where-Object { $null -ne $_ })
|    $schema = [pscustomobject]@{ Name = 'PrimaryResult'; Columns = $c; Rows = @(); RowsOmitted = $true }
|    # plain statements: an if used as a value would unroll the rows (one row would come back as that row, not a list)
|    $rows = $Results
|    if ($null -eq $rows) { $rows = [object[]]@() }
|    [pscustomobject]@{ Results = $rows; Columns = $c; Tables = @($schema); Error = $QueryError; Statistics = $null; Render = $null }
|}
|
|# =====================================================================================================================
|#  Storage data plane: blob, queue, table (OAuth bearer, x-ms-version)
|# =====================================================================================================================
|
|function Get-SIStorageApiVersion { '2021-08-06' }
|
|function Get-SIStorageUri {
|    param([Parameter(Mandatory)][string]$Account, [ValidateSet('blob', 'queue', 'table')][string]$Service = 'blob', [string]$Path = '', [string]$Query = '')
|    $p = (($Path -split '/') | ForEach-Object { [uri]::EscapeDataString($_) }) -join '/'
|    $u = 'https://{0}.{1}.core.windows.net/{2}' -f $Account, $Service, $p
|    if ($Query) { $u += '?' + $Query }
|    return $u
|}
|
|function Invoke-SIStorageRequest {
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Uri, $Body, [string]$ContentType, [hashtable]$Headers, [switch]$AllowNotFound, [int[]]$AllowStatus = @(), [switch]$AsBytes, [string]$What = 'Azure Storage request')
|    $h = @{ 'x-ms-version' = (Get-SIStorageApiVersion); 'x-ms-date' = [datetime]::UtcNow.ToString('R') }
|    if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|    if (-not $ContentType) { $ContentType = 'application/octet-stream' }
|    return (Invoke-SIAzRestRequest -Method $Method -Uri $Uri -Audience Storage -Body $Body -ContentType $ContentType -Headers $h -AllowNotFound:$AllowNotFound -AllowStatus $AllowStatus -AsBytes:$AsBytes -What $What)
|}
|
|function ConvertTo-SIStorageDate {
|    param([string]$Text)
|    $d = [DateTimeOffset]::MinValue
|    if ($Text -and [DateTimeOffset]::TryParse($Text, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::AssumeUniversal, [ref]$d)) { return $d }
|    return $null
|}
|
|function Get-SIBlobProperties {
|    <# HEAD of one blob: @{ Name; Length; LastModified; ETag; ContentType } or $null when it does not exist. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob)
|    $r = Invoke-SIStorageRequest -Method HEAD -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AllowNotFound -What ("Blob '{0}/{1}'" -f $Container, $Blob)
|    if (-not $r) { return $null }
|    $len = 0L; [void][long]::TryParse([string]$r.Headers['Content-Length'], [ref]$len)
|    return [pscustomobject]@{ Name = $Blob; Container = $Container; Length = $len; LastModified = (ConvertTo-SIStorageDate $r.Headers['Last-Modified']); ETag = [string]$r.Headers['ETag']; ContentType = [string]$r.Headers['Content-Type'] }
|}
|
|function Get-SIBlobList {
|    <# Every blob in -Container under -Prefix (List Blobs, following the marker). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [string]$Prefix)
|    $out = [System.Collections.Generic.List[object]]::new()
|    $marker = $null
|    do {
|        $q = 'restype=container&comp=list&maxresults=5000'
|        if ($Prefix) { $q += '&prefix=' + [uri]::EscapeDataString($Prefix) }
|        if ($marker) { $q += '&marker=' + [uri]::EscapeDataString($marker) }
|        $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query $q) -Headers @{ Accept = 'application/xml' } -What ("List blobs in '{0}'" -f $Container)
|        # The listing is XML (EnumerationResults). A cast `[xml]$text` that fails puts the WHOLE listing (up to 5,000 blobs)
|        # into its error text -- customer B 2026-10-15: "Cannot convert value "<?xml ... EnumerationResults ..." to type
|        # System.Xml.XmlDocument. Error: OutOfMemoryException" as the run's end text. Parsed here; a failure says what failed
|        # and why, in one short line, never the payload.
|        $x = New-Object System.Xml.XmlDocument
|        try { $x.LoadXml((([string]$r.Content) -replace '^\uFEFF', '')) }
|        catch {
|            $why = $_.Exception.Message; if ($_.Exception.InnerException) { $why = $_.Exception.InnerException.Message }
|            if ($why.Length -gt 300) { $why = $why.Substring(0, 300) }
|            throw ("The blob list of '{0}' (prefix '{1}') could not be read: {2}" -f $Container, $Prefix, $why)
|        }
|        foreach ($b in @($x.EnumerationResults.Blobs.Blob)) {
|            if ($null -eq $b) { continue }
|            $len = 0L; [void][long]::TryParse([string]$b.Properties.'Content-Length', [ref]$len)
|            [void]$out.Add([pscustomobject]@{ Name = [string]$b.Name; Container = $Container; Length = $len; LastModified = (ConvertTo-SIStorageDate ([string]$b.Properties.'Last-Modified')); ETag = [string]$b.Properties.Etag; ContentType = [string]$b.Properties.'Content-Type' })
|        }
|        $marker = [string]$x.EnumerationResults.NextMarker
|    } while ($marker)
|    return $out.ToArray()
|}
|
|function Get-SIBlobContent {
|    <# Download one blob: the bytes, or -Destination writes them to a file (returns the path). -AllowMissing: a blob that
|       does not exist (404) returns $null -- no error is raised or logged (2026-10-23: the pipeline's poll of a run's
|       records marker logged a TerminatingError 404 every 30 s, hiding the real errors). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob, [string]$Destination, [switch]$AllowMissing)
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AsBytes -AllowNotFound:$AllowMissing -What ("Download blob '{0}/{1}'" -f $Container, $Blob)
|    if ($AllowMissing -and $null -eq $r) { return $null }
|    # PLAIN statements, never `$bytes = if (...) { [byte[]]... }`: an `if` used as a value sends the array through the
|    # pipeline ONE BYTE AT A TIME into an object[] -- about 30 times the blob's size in memory. A new customer install
|    # 2026-10-12: the Azure collection's 13,562 assets made one large part, and reading it back ended in
|    # "System.OutOfMemoryException" on a job with 4 GiB and again with 8 GiB.
|    $bytes = $r.Bytes
|    if ($null -eq $bytes) { $bytes = [byte[]]::new(0) }
|    if (-not $Destination) { return ,$bytes }
|    [System.IO.File]::WriteAllBytes($Destination, $bytes)
|    return $Destination
|}
|
|function Set-SIBlobContent {
|    <# Upload one block blob (create or overwrite) from -File or -Bytes. -IfMatchETag makes it conditional (412 when
|       another writer got there first); -IfNoneMatch creates it only when it does not exist yet (409 / 412 when it does --
|       a claim exactly one writer wins). Returns the new ETag. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob,
|          [string]$File, [byte[]]$Bytes, [string]$IfMatchETag, [string]$ContentType = 'application/octet-stream', [switch]$IfNoneMatch)
|    if ($File) { $Bytes = [System.IO.File]::ReadAllBytes($File) }
|    if ($null -eq $Bytes) { $Bytes = [byte[]]@() }
|    $h = @{ 'x-ms-blob-type' = 'BlockBlob' }
|    if ($IfMatchETag) { $h['If-Match'] = $IfMatchETag }
|    if ($IfNoneMatch) { $h['If-None-Match'] = '*' }
|    $r = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -Body $Bytes -ContentType $ContentType -Headers $h -What ("Upload blob '{0}/{1}'" -f $Container, $Blob)
|    return [string]$r.Headers['ETag']
|}
|
|function Remove-SIBlob {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob)
|    $null = Invoke-SIStorageRequest -Method DELETE -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AllowNotFound -What ("Delete blob '{0}/{1}'" -f $Container, $Blob)
|}
|
|function Test-SIBlobContainer {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container)
|    $r = Invoke-SIStorageRequest -Method HEAD -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query 'restype=container') -AllowNotFound -What ("Container '{0}'" -f $Container)
|    if (-not $r) { return $null }
|    return [pscustomobject]@{ Name = $Container; LastModified = (ConvertTo-SIStorageDate $r.Headers['Last-Modified']); ETag = [string]$r.Headers['ETag'] }
|}
|
|function New-SIBlobContainer {
|    <# Create a private container; an existing one is not an error. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container)
|    $null = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query 'restype=container') -AllowStatus @(409) -What ("Create container '{0}'" -f $Container)
|    return [pscustomobject]@{ Name = $Container }
|}
|
|function Test-SIQueue {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue)
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Service queue -Path $Queue -Query 'comp=metadata') -AllowNotFound -What ("Queue '{0}'" -f $Queue)
|    return [bool]$r
|}
|
|function New-SIQueue {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue)
|    $null = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Service queue -Path $Queue) -AllowStatus @(409) -What ("Create queue '{0}'" -f $Queue)
|}
|
|function Send-SIQueueMessage {
|    <# Put one message. The text is sent as-is (XML-escaped), the encoding the Az.Storage 9 queue client uses. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][AllowEmptyString()][string]$Text)
|    $body = '<QueueMessage><MessageText>{0}</MessageText></QueueMessage>' -f [System.Security.SecurityElement]::Escape($Text)
|    $r = Invoke-SIStorageRequest -Method POST -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages")) -Body $body -ContentType 'application/xml' -What ("Send to queue '{0}'" -f $Queue)
|    $x = [xml]($r.Content -replace '^\uFEFF', '')
|    return [pscustomobject]@{ MessageId = [string]$x.QueueMessagesList.QueueMessage.MessageId; PopReceipt = [string]$x.QueueMessagesList.QueueMessage.PopReceipt }
|}
|
|function Receive-SIQueueMessage {
|    <# Lease one message for -VisibilityTimeoutSeconds: @{ MessageId; PopReceipt; MessageText; DequeueCount } or $null
|       when the queue is empty. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [int]$VisibilityTimeoutSeconds = 30)
|    $q = 'numofmessages=1&visibilitytimeout={0}' -f $VisibilityTimeoutSeconds
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages") -Query $q) -Headers @{ Accept = 'application/xml' } -What ("Receive from queue '{0}'" -f $Queue)
|    $x = [xml]($r.Content -replace '^\uFEFF', '')
|    $m = @($x.QueueMessagesList.QueueMessage) | Where-Object { $_ } | Select-Object -First 1
|    if (-not $m) { return $null }
|    return [pscustomobject]@{ MessageId = [string]$m.MessageId; PopReceipt = [string]$m.PopReceipt; MessageText = [string]$m.MessageText; DequeueCount = [int]$m.DequeueCount }
|}
|
|function Update-SIQueueMessage {
|    <#
|        RENEW the hold on one leased message: its visibility timeout is set to -VisibilityTimeoutSeconds from now (Update
|        Message). The message text goes back unchanged (-Text: as it was received). NEVER THROWS -- the answer says which:
|          @{ Ok = $true;  PopReceipt = <the NEW receipt: the old one is no longer valid> }
|          @{ Ok = $false; Lost = $true;  Why }   the message is gone (404) or another worker holds it (400 PopReceiptMismatch)
|          @{ Ok = $false; Lost = $false; Why }   anything else (network, sign-in, a 5xx): not known -- try again
|        Short timeouts and two attempts: this is called from a heartbeat, which must not hang on one request.
|        -Auth: the identity to sign in as (a second thread has no sign-in of its own; Resolve-SIAzRestAuth's answer).
|    #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][string]$MessageId, [Parameter(Mandatory)][string]$PopReceipt,
|          [Parameter(Mandatory)][int]$VisibilityTimeoutSeconds, [AllowEmptyString()][string]$Text = '', [hashtable]$Auth, [int]$TimeoutSec = 30)
|    try {
|        $q = 'popreceipt={0}&visibilitytimeout={1}' -f [uri]::EscapeDataString($PopReceipt), $VisibilityTimeoutSeconds
|        $body = '<QueueMessage><MessageText>{0}</MessageText></QueueMessage>' -f [System.Security.SecurityElement]::Escape($Text)
|        $h = @{ 'x-ms-version' = (Get-SIStorageApiVersion); 'x-ms-date' = [datetime]::UtcNow.ToString('R') }
|        $r = Invoke-SIAzRestRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages/$MessageId") -Query $q) -Audience Storage -Body $body `
|                -ContentType 'application/xml' -Headers $h -AllowStatus @(400, 404) -TimeoutSec $TimeoutSec -MaxAttempts 2 -Auth $Auth -What ("Renew the hold on a message of queue '{0}'" -f $Queue)
|        $code = 0; try { $code = [int]$r.StatusCode } catch { }
|        if ($code -ge 200 -and $code -lt 300) {
|            $new = [string]$r.Headers['x-ms-popreceipt']
|            if (-not $new) { return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = 'the queue answered without a new receipt' } }
|            return [pscustomobject]@{ Ok = $true; Lost = $false; PopReceipt = $new; Why = '' }
|        }
|        if ($code -eq 404) { return [pscustomobject]@{ Ok = $false; Lost = $true; PopReceipt = $PopReceipt; Why = 'the message is no longer in the queue' } }
|        $said = [string]$r.Content; try { if ($r.Headers -and $r.Headers['x-ms-error-code']) { $said += ' ' + [string]$r.Headers['x-ms-error-code'] } } catch { }
|        if ($code -eq 400 -and $said -match '(?i)PopReceiptMismatch|MessageNotFound') { return [pscustomobject]@{ Ok = $false; Lost = $true; PopReceipt = $PopReceipt; Why = 'another worker holds the message now' } }
|        return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = ('HTTP {0}: {1}' -f $code, (([string]$r.Content -replace '\s+', ' ').Trim() -replace '^(.{200}).*$', '$1...')) }
|    } catch {
|        return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = [string]$_.Exception.Message }
|    }
|}
|
|function Remove-SIQueueMessage {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][string]$MessageId, [Parameter(Mandatory)][string]$PopReceipt)
|    $q = 'popreceipt=' + [uri]::EscapeDataString($PopReceipt)
|    $null = Invoke-SIStorageRequest -Method DELETE -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages/$MessageId") -Query $q) -AllowNotFound -What ("Delete from queue '{0}'" -f $Queue)
|}
|
|function Get-SITableEntity {
|    <# One table entity (PartitionKey + RowKey) or $null; without -RowKey, every entity of the partition (following the
|       continuation headers). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Table, [Parameter(Mandatory)][string]$PartitionKey, [string]$RowKey)
|    $h = @{ Accept = 'application/json;odata=nometadata' }
|    $esc = { param($s) ([string]$s).Replace("'", "''") }
|    if ($RowKey) {
|        $path = "{0}(PartitionKey='{1}',RowKey='{2}')" -f $Table, [uri]::EscapeDataString((& $esc $PartitionKey)), [uri]::EscapeDataString((& $esc $RowKey))
|        $r = Invoke-SIStorageRequest -Method GET -Uri ('https://{0}.table.core.windows.net/{1}' -f $Account, $path) -Headers $h -ContentType 'application/json' -AllowNotFound -What ("Table '{0}' entity" -f $Table)
|        if (-not $r) { return $null }
|        return ($r.Content | ConvertFrom-Json)
|    }
|    $out = [System.Collections.Generic.List[object]]::new()
|    $filter = [uri]::EscapeDataString(("PartitionKey eq '{0}'" -f (& $esc $PartitionKey)))
|    $np = $null; $nr = $null
|    do {
|        $q = '$filter=' + $filter
|        if ($np) { $q += '&NextPartitionKey=' + [uri]::EscapeDataString($np) }
|        if ($nr) { $q += '&NextRowKey=' + [uri]::EscapeDataString($nr) }
|        $r = Invoke-SIStorageRequest -Method GET -Uri ('https://{0}.table.core.windows.net/{1}()?{2}' -f $Account, $Table, $q) -Headers $h -ContentType 'application/json' -What ("Table '{0}' query" -f $Table)
|        foreach ($e in @(($r.Content | ConvertFrom-Json).value)) { if ($e) { [void]$out.Add($e) } }
|        $np = [string]$r.Headers['x-ms-continuation-NextPartitionKey']; $nr = [string]$r.Headers['x-ms-continuation-NextRowKey']
|    } while ($np)
|    return $out.ToArray()
|}
|
|function Set-SITableEntity {
|    <# UPSERT one entity (Insert Or Replace; -Merge = Insert Or Merge). -Entity is a hashtable of properties. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Table, [Parameter(Mandatory)][string]$PartitionKey,
|          [Parameter(Mandatory)][string]$RowKey, [hashtable]$Entity = @{}, [switch]$Merge)
|    $e = [ordered]@{ PartitionKey = $PartitionKey; RowKey = $RowKey }
|    foreach ($k in $Entity.Keys) { if ($k -notin 'PartitionKey', 'RowKey') { $e[$k] = $Entity[$k] } }
|    $esc = { param($s) ([string]$s).Replace("'", "''") }
|    $path = "{0}(PartitionKey='{1}',RowKey='{2}')" -f $Table, [uri]::EscapeDataString((& $esc $PartitionKey)), [uri]::EscapeDataString((& $esc $RowKey))
|    $bytes = [System.Text.Encoding]::UTF8.GetBytes(($e | ConvertTo-Json -Depth 5 -Compress))
|    $null = Invoke-SIStorageRequest -Method $(if ($Merge) { 'MERGE' } else { 'PUT' }) -Uri ('https://{0}.table.core.windows.net/{1}' -f $Account, $path) -Body $bytes `
|                -ContentType 'application/json' -Headers @{ Accept = 'application/json;odata=nometadata' } -What ("Table '{0}' upsert" -f $Table)
|}
|
|# =====================================================================================================================
|#  The wrappers -- each forwards to its REST twin below
|# =====================================================================================================================
|# Each declares the parameters SecurityInsight's call sites use, UNTYPED except switches, and forwards @PSBoundParameters
|# -- never @args (measured: @args splits -Name:$value into a switch plus a positional value).
|function Connect-SIAzAccount {
|    [CmdletBinding()]
|    param([switch]$Identity, $AccountId, [switch]$ServicePrincipal, $ApplicationId, $CertificateThumbprint,
|          $CertificatePath, $CertificatePassword, $Credential,
|          [Alias('TenantId')]$Tenant, [Alias('SubscriptionId')]$Subscription, $Scope)
|    return (Connect-SIAzAccountRest @PSBoundParameters)
|}
|function Disconnect-SIAzAccount {
|    [CmdletBinding()] param($Scope)
|    return (Disconnect-SIAzAccountRest @PSBoundParameters)
|}
|function Disable-SIAzContextAutosave {
|    [CmdletBinding()] param($Scope)
|    return (Disable-SIAzContextAutosaveRest @PSBoundParameters)
|}
|function Get-SIAzContext {
|    [CmdletBinding()] param()
|    return (Get-SIAzContextRest @PSBoundParameters)
|}
|function Set-SIAzContext {
|    [CmdletBinding()]
|    param([Alias('SubscriptionId', 'SubscriptionName')]$Subscription, [Alias('TenantId', 'Domain')]$Tenant, $Context, $Scope)
|    return (Set-SIAzContextRest @PSBoundParameters)
|}
|function Get-SIAzAccessToken {
|    [CmdletBinding()] param($ResourceUrl, $TenantId)
|    return (Get-SIAzAccessTokenRest @PSBoundParameters)
|}
|function Get-SIAzSubscription {
|    [CmdletBinding()] param($TenantId, $SubscriptionId)
|    return (Get-SIAzSubscriptionRest @PSBoundParameters)
|}
|function Invoke-SIAzRestMethod {
|    [CmdletBinding()] param($Path, $Method, $Payload)
|    return (Invoke-SIAzRestMethodRest @PSBoundParameters)
|}
|function Invoke-SIAzOperationalInsightsQuery {
|    # -AllowPartial: the caller reads .Error itself (Invoke-SILaQuery refuses a cut answer otherwise); -OnPage / -PageBytes:
|    # the rows a page at a time (Invoke-SILaQuery)
|    [CmdletBinding()] param($WorkspaceId, $Query, $Wait, $Timespan, [switch]$AllowPartial, [scriptblock]$OnPage, [long]$PageBytes)
|    return (Invoke-SIAzOperationalInsightsQueryRest @PSBoundParameters)
|}
|function Get-SIAzOperationalInsightsWorkspace {
|    [CmdletBinding()] param($ResourceGroupName, $Name)
|    return (Get-SIAzOperationalInsightsWorkspaceRest @PSBoundParameters)
|}
|function New-SIAzOperationalInsightsWorkspace {
|    [CmdletBinding()] param($ResourceGroupName, $Name, $Location, $Sku, $RetentionInDays)
|    return (New-SIAzOperationalInsightsWorkspaceRest @PSBoundParameters)
|}
|function Search-SIAzGraph {
|    [CmdletBinding()] param($Query, $First, $Skip, $Subscription, $ManagementGroup, $SkipToken)
|    return ,(Search-SIAzGraphRest @PSBoundParameters)   # one page object, not its rows
|}
|function Get-SIAzKeyVaultSecret {
|    [CmdletBinding()] param($VaultName, $Name, [switch]$AsPlainText)
|    return (Get-SIAzKeyVaultSecretRest @PSBoundParameters)
|}
|function Set-SIAzKeyVaultSecret {
|    [CmdletBinding()] param($VaultName, $Name, $SecretValue, $ContentType)
|    return (Set-SIAzKeyVaultSecretRest @PSBoundParameters)
|}
|function Get-SIAzResourceGroup {
|    [CmdletBinding()] param($Name)
|    return (Get-SIAzResourceGroupRest @PSBoundParameters)
|}
|function New-SIAzResourceGroup {
|    [CmdletBinding()] param($Name, $Location, $Tag)
|    return (New-SIAzResourceGroupRest @PSBoundParameters)
|}
|function Get-SIAzRoleAssignment {
|    [CmdletBinding()] param($ObjectId, $Scope, $RoleDefinitionName)
|    return (Get-SIAzRoleAssignmentRest @PSBoundParameters)
|}
|function New-SIAzRoleAssignment {
|    [CmdletBinding()] param($ObjectId, $Scope, $RoleDefinitionName, $Description)
|    return (New-SIAzRoleAssignmentRest @PSBoundParameters)
|}
|function Get-SIAzRoleDefinition {
|    [CmdletBinding()] param([switch]$Custom, $Name, $Scope)
|    return (Get-SIAzRoleDefinitionRest @PSBoundParameters)
|}
|function Get-SIAzTag {
|    [CmdletBinding()] param($ResourceId)
|    return (Get-SIAzTagRest @PSBoundParameters)
|}
|function Update-SIAzTag {
|    [CmdletBinding()] param($ResourceId, $Tag, $Operation)
|    return (Update-SIAzTagRest @PSBoundParameters)
|}
|function Get-SIAzADServicePrincipal {
|    [CmdletBinding()] param($ApplicationId, $ObjectId)
|    return (Get-SIAzADServicePrincipalRest @PSBoundParameters)
|}
|function Get-SIAzDataCollectionEndpoint {
|    [CmdletBinding()] param($Name, $ResourceGroupName)
|    return (Get-SIAzDataCollectionEndpointRest @PSBoundParameters)
|}
|function New-SIAzDataCollectionEndpoint {
|    [CmdletBinding()] param($Name, $ResourceGroupName, $Location, $NetworkAclsPublicNetworkAccess)
|    return (New-SIAzDataCollectionEndpointRest @PSBoundParameters)
|}
|function Get-SIAzDataCollectionRule {
|    [CmdletBinding()] param($Name, $ResourceGroupName)
|    return (Get-SIAzDataCollectionRuleRest @PSBoundParameters)
|}
|function New-SIAzStorageContext {
|    [CmdletBinding()] param($StorageAccountName, [switch]$UseConnectedAccount)
|    return (New-SIAzStorageContextRest @PSBoundParameters)
|}
|function Get-SIAzStorageAccount {
|    [CmdletBinding()] param($ResourceGroupName, $Name)
|    return (Get-SIAzStorageAccountRest @PSBoundParameters)
|}
|function New-SIAzStorageAccount {
|    [CmdletBinding()]
|    param($ResourceGroupName, $Name, $Location, $SkuName, $Kind, $EnableHttpsTrafficOnly,
|          $MinimumTlsVersion, $AllowBlobPublicAccess, $PublicNetworkAccess)
|    return (New-SIAzStorageAccountRest @PSBoundParameters)
|}
|function Get-SIAzStorageContainer {
|    [CmdletBinding()] param($Name, $Context)
|    return (Get-SIAzStorageContainerRest @PSBoundParameters)
|}
|function New-SIAzStorageContainer {
|    [CmdletBinding()] param($Name, $Context, $Permission)
|    return (New-SIAzStorageContainerRest @PSBoundParameters)
|}
|function Get-SIAzStorageBlob {
|    [CmdletBinding()] param($Container, $Blob, $Prefix, $Context)
|    return (Get-SIAzStorageBlobRest @PSBoundParameters)
|}
|function Get-SIAzStorageBlobContent {
|    [CmdletBinding()] param($Container, $Blob, $CloudBlob, $Destination, $Context, [switch]$Force)
|    return (Get-SIAzStorageBlobContentRest @PSBoundParameters)
|}
|function Set-SIAzStorageBlobContent {
|    [CmdletBinding()] param($File, $Container, $Blob, $Context, [switch]$Force)
|    return (Set-SIAzStorageBlobContentRest @PSBoundParameters)
|}
|function Remove-SIAzStorageBlob {
|    [CmdletBinding()] param($Container, $Blob, $Context, [switch]$Force)
|    return (Remove-SIAzStorageBlobRest @PSBoundParameters)
|}
|function Start-SIAzStorageBlobCopy {
|    [CmdletBinding()] param($SrcContainer, $SrcBlob, $DestContainer, $DestBlob, $Context, [switch]$Force)
|    return (Start-SIAzStorageBlobCopyRest @PSBoundParameters)
|}
|function Get-SIAzStorageQueue {
|    [CmdletBinding()] param($Name, $Context)
|    return (Get-SIAzStorageQueueRest @PSBoundParameters)
|}
|function New-SIAzStorageQueue {
|    [CmdletBinding()] param($Name, $Context)
|    return (New-SIAzStorageQueueRest @PSBoundParameters)
|}
|
|function Set-SIAzStorageBlobContentIfMatch {
|    <# The ledger's CONDITIONAL write (only when the blob still has -IfMatchETag): PUT with If-Match. A lost race fails
|       with '412 ConditionNotMet'. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$File, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob,
|          [Parameter(Mandatory)][object]$Context, [Parameter(Mandatory)][string]$IfMatchETag)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $null = Set-SIBlobContent -Account $acct -Container $Container -Blob $Blob -File $File -IfMatchETag $IfMatchETag
|}
|# =====================================================================================================================
|#  The REST twins -- what each wrapper does with no Az module
|# =====================================================================================================================
|
|function Write-SIAzRestNotFound {
|    <# A lookup that found nothing, the way the Az cmdlet reports it: a NON-terminating error, so -ErrorAction
|       SilentlyContinue yields $null and -ErrorAction Stop throws. #>
|    param([Parameter(Mandatory)]$Cmdlet, [Parameter(Mandatory)][string]$Message, [string]$Target)
|    $er = New-Object System.Management.Automation.ErrorRecord((New-Object System.Exception($Message)), 'SIAzRestNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $Target)
|    $Cmdlet.WriteError($er)
|}
|
|function Get-SIAzRestSubscriptionId {
|    <# The current subscription: Set-SIAzContext / Connect -Subscription, else the install's workspace subscription,
|       else the first enabled subscription the identity sees (what Connect-AzAccount selects). #>
|    param([switch]$NoLookup)
|    $st = Get-SIAzRestState
|    if ($st.SubscriptionId) { return [string]$st.SubscriptionId }
|    $s = [string](Get-SIAzRestValue 'SI_AzSubscriptionId')
|    if (-not $s -and [string](Get-SIAzRestValue 'SI_WorkspaceResourceId') -match '/subscriptions/([^/]+)/') { $s = $Matches[1] }
|    if (-not $s) { $s = [string](Get-SIAzRestValue 'SubscriptionId') }
|    # in an Invardia Support session, the first subscription the environment names
|    if (-not $s) { $sess = Get-SISupportSession; if ($sess -and $sess.SubscriptionId) { $s = [string]$sess.SubscriptionId } }
|    if (-not $s -and -not $NoLookup) {
|        try {
|            $first = @(Invoke-SIArm -Path '/subscriptions' -ApiVersion '2022-12-01' -List | Where-Object { [string]$_.state -eq 'Enabled' }) | Select-Object -First 1
|            if ($first) { $s = [string]$first.subscriptionId }
|        } catch { }
|    }
|    if ($s) { $st.SubscriptionId = $s }
|    return $s
|}
|
|function Get-SIAzRestTenantId {
|    $st = Get-SIAzRestState
|    if ($st.TenantId) { return [string]$st.TenantId }
|    $a = Resolve-SIAzRestAuth
|    $t = [string]$a.TenantId
|    if (-not $t) {
|        # a managed identity knows its tenant: read it from its own ARM token
|        try { $c = ConvertFrom-SIJwtPayload (Get-SIAzureToken -Audience Arm); if ($c) { $t = [string]$c.tid } } catch { }
|    }
|    if ($t) { $st.TenantId = $t }
|    return $t
|}
|
|function Connect-SIAzAccountRest {
|    <# RECORDS the identity; no sign-in happens here (each REST call mints its token when it needs one). #>
|    [CmdletBinding()]
|    param([switch]$Identity, [string]$AccountId, [switch]$ServicePrincipal, [string]$ApplicationId, [string]$CertificateThumbprint,
|          [string]$CertificatePath, [securestring]$CertificatePassword, [pscredential]$Credential,
|          [Alias('TenantId')][string]$Tenant, [Alias('SubscriptionId')][string]$Subscription, [string]$Scope)
|    $st = Get-SIAzRestState
|    $conn = $null
|    if ($Identity) {
|        $cid = if ($AccountId) { $AccountId } else { [string](Get-SIAzRestValue 'SI_UAMI_ClientId', 'SI_ManagedIdentityClientId') }
|        $conn = @{ Mode = 'ManagedIdentity'; ClientId = $cid }
|    } elseif ($Credential) {
|        $conn = @{ Mode = 'Secret'; AppId = [string]$Credential.UserName; TenantId = $Tenant; Secret = $Credential.GetNetworkCredential().Password }
|    } elseif ($CertificateThumbprint -or $CertificatePath) {
|        $thumb = $CertificateThumbprint
|        if ($CertificatePath) {
|            # the PFX the container wrote: the token signer looks a certificate up by thumbprint in the X509 store, so
|            # it goes into CurrentUser\My (the only store a Linux container has) unless it is already there
|            $pw = if ($CertificatePassword) { [System.Net.NetworkCredential]::new('', $CertificatePassword).Password } else { '' }
|            $flags = [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet
|            $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new([System.IO.File]::ReadAllBytes($CertificatePath), $pw, $flags)
|            $thumb = [string]$cert.Thumbprint
|            Initialize-SIAzRestHelpers
|            if (-not (Get-SICertificateFromStore -Thumbprint $thumb)) {
|                $store = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', 'CurrentUser')
|                try { $store.Open('ReadWrite'); $store.Add($cert) } finally { $store.Close() }
|            }
|        }
|        $conn = @{ Mode = 'Certificate'; AppId = $ApplicationId; TenantId = $Tenant; Thumbprint = ($thumb -replace '\s', '') }
|    } else {
|        throw 'Connect-SIAzAccount (REST): name the identity -- -Identity, -Credential, or -ApplicationId with -CertificateThumbprint / -CertificatePath.'
|    }
|    $st.Connection = $conn
|    $st.TenantId = if ($Tenant) { $Tenant } else { $null }
|    $st.SubscriptionId = if ($Subscription) { $Subscription } else { $null }
|    $st.Cache = @{}
|    return (Get-SIAzContextRest)
|}
|
|function Disconnect-SIAzAccountRest {
|    [CmdletBinding()] param([string]$Scope)
|    $st = Get-SIAzRestState
|    $st.Connection = $null; $st.SubscriptionId = $null; $st.TenantId = $null; $st.Cache = @{}
|    $rc = Get-Variable -Scope Global -Name SI_LogIngestRunCache -ValueOnly -ErrorAction Ignore
|    if ($rc -is [hashtable]) { $rc.Tokens = @{} }
|}
|
|function Disable-SIAzContextAutosaveRest { [CmdletBinding()] param([string]$Scope) }
|
|function Get-SIAzContextRest {
|    <# The context object the call sites read (Subscription.Id / .Name, Tenant.Id, Account.Id / .Type), or $null when
|       no identity is configured. #>
|    [CmdletBinding()] param()
|    try { $a = Resolve-SIAzRestAuth } catch { return $null }
|    $sub = Get-SIAzRestSubscriptionId
|    $tid = Get-SIAzRestTenantId
|    $acct = switch ($a.Mode) { 'ManagedIdentity' { [pscustomobject]@{ Id = $(if ($a.ClientId) { $a.ClientId } else { 'MSI' }); Type = 'ManagedService' } } default { [pscustomobject]@{ Id = $a.AppId; Type = 'ServicePrincipal' } } }
|    return [pscustomobject]@{
|        PSTypeName   = 'SI.AzRest.Context'
|        Name         = ('{0} ({1})' -f $sub, $acct.Id)
|        Account      = $acct
|        Subscription = $(if ($sub) { [pscustomobject]@{ Id = $sub; SubscriptionId = $sub; Name = $sub; TenantId = $tid; ExtendedProperties = @{} } } else { $null })
|        Tenant       = [pscustomobject]@{ Id = $tid; TenantId = $tid }
|        Environment  = [pscustomobject]@{ Name = 'AzureCloud' }
|    }
|}
|
|function Set-SIAzContextRest {
|    [CmdletBinding()]
|    param([Alias('SubscriptionId', 'SubscriptionName')][string]$Subscription, [Alias('TenantId', 'Domain')][string]$Tenant, [object]$Context, [string]$Scope)
|    $st = Get-SIAzRestState
|    if ($Context -and $Context.Subscription) { $Subscription = [string]$Context.Subscription.Id }
|    if ($Subscription) { $st.SubscriptionId = $Subscription }
|    if ($Tenant) { $st.TenantId = $Tenant }
|    return (Get-SIAzContextRest)
|}
|
|function Get-SIAzAccessTokenRest {
|    [CmdletBinding()] param([string]$ResourceUrl, [string]$TenantId)
|    $res = if ($ResourceUrl) { $ResourceUrl } else { 'https://management.azure.com/' }
|    $tok = Get-SIAzureToken -Resource $res
|    $c = ConvertFrom-SIJwtPayload $tok
|    $exp = [DateTimeOffset]::UtcNow.AddMinutes(45)
|    if ($c -and $c.exp) { try { $exp = [DateTimeOffset]::FromUnixTimeSeconds([long]$c.exp) } catch { } }
|    return [pscustomobject]@{ Token = $tok; ExpiresOn = $exp; Type = 'Bearer'; TenantId = $(if ($c) { [string]$c.tid } else { $null }); UserId = $(if ($c) { [string]$c.appid } else { $null }) }
|}
|
|function Get-SIAzSubscriptionRest {
|    [CmdletBinding()] param([string]$TenantId, [string]$SubscriptionId)
|    foreach ($s in @(Invoke-SIArm -Path '/subscriptions' -ApiVersion '2022-12-01' -List)) {
|        if ($TenantId -and [string]$s.tenantId -and [string]$s.tenantId -ne $TenantId) { continue }
|        if ($SubscriptionId -and [string]$s.subscriptionId -ne $SubscriptionId) { continue }
|        [pscustomobject]@{ Id = [string]$s.subscriptionId; SubscriptionId = [string]$s.subscriptionId; Name = [string]$s.displayName; State = [string]$s.state; TenantId = [string]$s.tenantId; HomeTenantId = [string]$s.tenantId }
|    }
|}
|
|function Invoke-SIAzRestMethodRest {
|    <# As Invoke-AzRestMethod: never throws on an HTTP status; returns StatusCode / Content / Headers / Method. #>
|    [CmdletBinding()] param([string]$Path, [string]$Method = 'GET', [string]$Payload)
|    if (-not $Method) { $Method = 'GET' }
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path }
|    $body = if ($Payload) { $Payload } else { $null }
|    # #564: a POST action with no body sends '{}' (an empty JSON body was refused with HTTP 415)
|    if ($Method.ToUpperInvariant() -eq 'POST' -and $null -eq $body) { $body = '{}' }
|    # #548: inside an Invardia support session through the recording wrapper, never a raw token
|    if (Test-SISupportRequestRoute -Audience Arm) { $r = Invoke-SISupportHttp -Method $Method -Uri $uri -Body $body -ContentType 'application/json' -Audience Arm }
|    else {
|        $tok = Get-SIAzureToken -Audience Arm
|        $r = Invoke-SIAzRestHttp -Method $Method -Uri $uri -Headers @{ Authorization = ('Bearer ' + $tok) } -Body $body -ContentType 'application/json'
|    }
|    return [pscustomobject]@{ StatusCode = [int]$r.StatusCode; Content = [string]$r.Content; Headers = $r.Headers; Method = $Method.ToUpperInvariant() }
|}
|
|function Invoke-SIAzOperationalInsightsQueryRest {
|    [CmdletBinding()] param([string]$WorkspaceId, [string]$Query, [int]$Wait, [timespan]$Timespan, [switch]$AllowPartial, [scriptblock]$OnPage, [long]$PageBytes)
|    $p = @{ WorkspaceId = $WorkspaceId; Query = $Query }
|    if ($PSBoundParameters.ContainsKey('Wait')) { $p['Wait'] = $Wait }
|    if ($PSBoundParameters.ContainsKey('Timespan')) { $p['Timespan'] = $Timespan }
|    if ($AllowPartial) { $p['AllowPartial'] = $true }
|    if ($OnPage) { $p['OnPage'] = $OnPage }
|    if ($PSBoundParameters.ContainsKey('PageBytes') -and $PageBytes -gt 0) { $p['PageBytes'] = $PageBytes }
|    return (Invoke-SILaQuery @p)
|}
|
|function ConvertTo-SIAzWorkspaceObject {
|    param($Ws)
|    $cid = [guid]::Empty
|    [void][guid]::TryParse([string]$Ws.properties.customerId, [ref]$cid)
|    $rg = if ([string]$Ws.id -match '/resourceGroups/([^/]+)/') { $Matches[1] } else { $null }
|    [pscustomobject]@{
|        Name = [string]$Ws.name; ResourceId = [string]$Ws.id; ResourceGroupName = $rg; Location = [string]$Ws.location
|        CustomerId = $cid; Sku = [string]$Ws.properties.sku.name; RetentionInDays = $Ws.properties.retentionInDays
|        ProvisioningState = [string]$Ws.properties.provisioningState; Tags = $Ws.tags
|    }
|}
|
|function Get-SIAzOperationalInsightsWorkspaceRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($ResourceGroupName -and $Name) {
|        $ws = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces/$Name") -ApiVersion '2022-10-01' -AllowNotFound
|        if (-not $ws) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The Log Analytics workspace '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzWorkspaceObject $ws)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces" } else { "/subscriptions/$sub/providers/Microsoft.OperationalInsights/workspaces" }
|    foreach ($w in @(Invoke-SIArm -Path $path -ApiVersion '2022-10-01' -List)) {
|        if ($Name -and [string]$w.name -ne $Name) { continue }
|        ConvertTo-SIAzWorkspaceObject $w
|    }
|}
|
|function New-SIAzOperationalInsightsWorkspaceRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name, [string]$Location, [string]$Sku = 'PerGB2018', [int]$RetentionInDays = 30)
|    if (-not $Sku) { $Sku = 'PerGB2018' }
|    $sub = Get-SIAzRestSubscriptionId
|    $body = @{ location = $Location; properties = @{ sku = @{ name = $Sku } } }
|    if ($PSBoundParameters.ContainsKey('RetentionInDays')) { $body.properties['retentionInDays'] = $RetentionInDays }
|    $wsPath = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces/$Name"
|    $ws = Invoke-SIArm -Method PUT -Path $wsPath -ApiVersion '2022-10-01' -Body $body
|    # the create is asynchronous (its answer can be empty, or a workspace still being made): wait until the workspace is
|    # THERE and provisioned -- its id and customer id are used right after this returns. Not ready in time = a clear stop.
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    $state = ''
|    for ($i = 0; $i -lt 60; $i++) {
|        $state = if ($ws -and $ws.properties) { [string]$ws.properties.provisioningState } else { '' }
|        if ($ws -and [string]$ws.id -and ($state -eq 'Succeeded' -or -not $state)) { return (ConvertTo-SIAzWorkspaceObject $ws) }
|        if ($state -in 'Failed', 'Canceled') { throw ("The Log Analytics workspace '{0}' was not created: Azure reports it {1} -- see the activity log of resource group '{2}' for its reason." -f $Name, $state, $ResourceGroupName) }
|        if ($sleep -is [scriptblock]) { & $sleep 5 } else { Start-Sleep -Seconds 5 }
|        $ws = Invoke-SIArm -Path $wsPath -ApiVersion '2022-10-01' -AllowNotFound
|    }
|    throw ("The Log Analytics workspace '{0}' is not ready 5 minutes after it was created (Azure shows: {1})." -f $Name, $(if ($state) { $state } else { 'not there yet' }))
|}
|
|function New-SIAzGraphPage {
|    <# A page shaped like Search-AzGraph's response: enumerates as the rows, with .Data and .SkipToken. #>
|    param([object[]]$Rows, [string]$SkipToken)
|    $list = [System.Collections.Generic.List[object]]::new()
|    foreach ($r in @($Rows)) { if ($null -ne $r) { [void]$list.Add($r) } }
|    Add-Member -InputObject $list -NotePropertyName Data -NotePropertyValue $list.ToArray() -Force
|    Add-Member -InputObject $list -NotePropertyName SkipToken -NotePropertyValue $(if ($SkipToken) { $SkipToken } else { $null }) -Force
|    return ,$list
|}
|
|function Search-SIAzGraphRest {
|    [CmdletBinding()] param([string]$Query, [int]$First = 100, [int]$Skip, [string[]]$Subscription, [string[]]$ManagementGroup, [string]$SkipToken)
|    if (-not $PSBoundParameters.ContainsKey('First') -or $First -le 0) { $First = 100 }
|    $page = Invoke-SIResourceGraphPage -Query $Query -Subscription $Subscription -ManagementGroup $ManagementGroup -First $First -Skip $Skip -SkipToken $SkipToken
|    $p = New-SIAzGraphPage -Rows $page.Data -SkipToken $page.SkipToken
|    return ,$p
|}
|
|function Get-SIAzKeyVaultSecretRest {
|    [CmdletBinding()] param([string]$VaultName, [string]$Name, [switch]$AsPlainText)
|    $j = Get-SIKeyVaultSecretRaw -VaultName $VaultName -Name $Name
|    if (-not $j) { return }
|    if ($AsPlainText) { return [string]$j.value }
|    $sec = New-Object System.Security.SecureString
|    foreach ($ch in ([string]$j.value).ToCharArray()) { $sec.AppendChar($ch) }
|    $sec.MakeReadOnly()
|    return [pscustomobject]@{ VaultName = $VaultName; Name = $Name; Id = [string]$j.id; SecretValue = $sec; ContentType = [string]$j.contentType; Enabled = $j.attributes.enabled; Tags = $j.tags }
|}
|
|function Set-SIAzKeyVaultSecretRest {
|    <# PUT secrets/{name}: a new version of the secret. -SecretValue is a SecureString (as for the cmdlet) or plain text. #>
|    [CmdletBinding()] param([string]$VaultName, [string]$Name, $SecretValue, [string]$ContentType)
|    $plain = if ($SecretValue -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $SecretValue).Password } else { [string]$SecretValue }
|    $body = @{ value = $plain }
|    if ($ContentType) { $body.contentType = $ContentType }
|    $uri = 'https://{0}.vault.azure.net/secrets/{1}?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name)
|    $r = Invoke-SIAzRestRequest -Method PUT -Uri $uri -Audience KeyVault -Body ($body | ConvertTo-Json -Compress) -What ("Key Vault secret '{0}' in '{1}'" -f $Name, $VaultName)
|    $j = $r.Content | ConvertFrom-Json
|    return [pscustomobject]@{ VaultName = $VaultName; Name = $Name; Id = [string]$j.id; ContentType = [string]$j.contentType; Enabled = $j.attributes.enabled }
|}
|
|function ConvertTo-SIAzResourceGroupObject {
|    param($Rg)
|    [pscustomobject]@{ ResourceGroupName = [string]$Rg.name; Location = [string]$Rg.location; ResourceId = [string]$Rg.id; ProvisioningState = [string]$Rg.properties.provisioningState; Tags = $Rg.tags }
|}
|
|function Get-SIAzResourceGroupRest {
|    [CmdletBinding()] param([string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($Name) {
|        $rg = Invoke-SIArm -Path ("/subscriptions/$sub/resourcegroups/$Name") -ApiVersion '2021-04-01' -AllowNotFound
|        if (-not $rg) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Provided resource group '{0}' does not exist." -f $Name) -Target $Name; return }
|        return (ConvertTo-SIAzResourceGroupObject $rg)
|    }
|    foreach ($rg in @(Invoke-SIArm -Path ("/subscriptions/$sub/resourcegroups") -ApiVersion '2021-04-01' -List)) { ConvertTo-SIAzResourceGroupObject $rg }
|}
|
|function New-SIAzResourceGroupRest {
|    [CmdletBinding()] param([string]$Name, [string]$Location, [hashtable]$Tag)
|    $sub = Get-SIAzRestSubscriptionId
|    $body = @{ location = $Location }
|    if ($Tag) { $body['tags'] = $Tag }
|    $rg = Invoke-SIArm -Method PUT -Path ("/subscriptions/$sub/resourcegroups/$Name") -ApiVersion '2021-04-01' -Body $body
|    return (ConvertTo-SIAzResourceGroupObject $rg)
|}
|
|function Get-SIAzRestRoleDefinitions {
|    <# Role definitions visible at -Scope (built-in + custom), cached per scope for the run. #>
|    param([string]$Scope, [switch]$CustomOnly)
|    $st = Get-SIAzRestState
|    $key = 'roledefs|' + $Scope.ToLowerInvariant() + '|' + [string][bool]$CustomOnly
|    if ($st.Cache.ContainsKey($key)) { return $st.Cache[$key] }
|    $path = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleDefinitions'
|    if ($CustomOnly) { $path += '?$filter=' + [uri]::EscapeDataString("type eq 'CustomRole'") }
|    $defs = @(Invoke-SIArm -Path $path -ApiVersion '2022-04-01' -List)
|    $st.Cache[$key] = $defs
|    return $defs
|}
|
|function Get-SIAzRestRoleDefinitionNames {
|    <#
|        The role NAME of every role definition visible at -Scope, by its id (lowercase): @{ <id> = <roleName> }. For the
|        role-assignment read, which needs only the name. Built-in roles are the same at every scope: they are read ONCE per
|        run and kept as names only; a scope's custom roles are read per scope, names only. The full definitions (every
|        permission of ~800 built-in roles) are never kept. customer B 2026-10-15: the identity producer read the role
|        assignments of 1,195 subscriptions and kept the WHOLE definition list of every one of them (Get-SIAzRestRoleDefinitions
|        caches per scope) -- the process ran out of memory in its sixth minute and every read after that failed.
|        -Fetch (tests): { param($Path) } -> the ARM rows of that list.
|    #>
|    param([Parameter(Mandatory)][string]$Scope, [scriptblock]$Fetch)
|    $st = Get-SIAzRestState
|    $read = { param($p) if ($Fetch) { @(& $Fetch $p) } else { @(Invoke-SIArm -Path $p -ApiVersion '2022-04-01' -List) } }
|    $base = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleDefinitions?$filter='
|    $bk = 'roledefnames|builtin'
|    if (-not $st.Cache.ContainsKey($bk)) {
|        $m = @{}
|        foreach ($d in (& $read ($base + [uri]::EscapeDataString("type eq 'BuiltInRole'")))) { if ($d -and $d.name) { $m[([string]$d.name).ToLowerInvariant()] = [string]$d.properties.roleName } }
|        $st.Cache[$bk] = $m
|    }
|    $ck = 'roledefnames|custom|' + $Scope.ToLowerInvariant()
|    if (-not $st.Cache.ContainsKey($ck)) {
|        $m = @{}
|        foreach ($d in (& $read ($base + [uri]::EscapeDataString("type eq 'CustomRole'")))) { if ($d -and $d.name) { $m[([string]$d.name).ToLowerInvariant()] = [string]$d.properties.roleName } }
|        $st.Cache[$ck] = $m
|    }
|    [pscustomobject]@{ BuiltIn = $st.Cache[$bk]; Custom = $st.Cache[$ck] }
|}
|
|function ConvertTo-SIAzRoleDefinitionObject {
|    param($D)
|    $perm = @($D.properties.permissions) | Select-Object -First 1
|    [pscustomobject]@{
|        Name = [string]$D.properties.roleName; Id = [string]$D.name; IsCustom = ([string]$D.properties.type -eq 'CustomRole')
|        Description = [string]$D.properties.description
|        Actions = @($perm.actions); NotActions = @($perm.notActions); DataActions = @($perm.dataActions); NotDataActions = @($perm.notDataActions)
|        AssignableScopes = @($D.properties.assignableScopes)
|    }
|}
|
|function Get-SIAzRoleDefinitionRest {
|    [CmdletBinding()] param([switch]$Custom, [string]$Name, [string]$Scope)
|    if (-not $Scope) { $Scope = '/subscriptions/' + (Get-SIAzRestSubscriptionId) }
|    $out = @(Get-SIAzRestRoleDefinitions -Scope $Scope -CustomOnly:$Custom | ForEach-Object { ConvertTo-SIAzRoleDefinitionObject $_ })
|    if ($Name) { $out = @($out | Where-Object { $_.Name -eq $Name }) }
|    return $out
|}
|
|function Resolve-SIAzRestPrincipalNames {
|    <# DisplayName per object id, best effort (Microsoft Graph directoryObjects/getByIds). Empty on any failure: a name
|       is informational, never a reason to fail the read. #>
|    param([string[]]$Ids)
|    $map = @{}
|    $ids = @($Ids | Where-Object { $_ } | Select-Object -Unique)
|    for ($i = 0; $i -lt $ids.Count; $i += 1000) {
|        $chunk = @($ids[$i..([Math]::Min($i + 999, $ids.Count - 1))])
|        try {
|            $r = Invoke-SIAzRestRequest -Method POST -Uri 'https://graph.microsoft.com/v1.0/directoryObjects/getByIds' -Audience Graph `
|                     -Body (@{ ids = $chunk } | ConvertTo-Json -Compress) -What 'Microsoft Graph getByIds' -MaxAttempts 3
|            foreach ($o in @(($r.Content | ConvertFrom-Json).value)) { if ($o.id) { $map[[string]$o.id] = [string]$o.displayName } }
|        } catch { Write-Verbose ('principal names not resolved: {0}' -f $_.Exception.Message) }
|    }
|    return $map
|}
|
|function Get-SIAzRoleAssignmentRest {
|    [CmdletBinding()] param([string]$ObjectId, [string]$Scope, [string]$RoleDefinitionName)
|    $explicitScope = [bool]$Scope
|    if (-not $Scope) { $Scope = '/subscriptions/' + (Get-SIAzRestSubscriptionId) }
|    $path = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments'
|    if ($ObjectId) { $path += '?$filter=' + [uri]::EscapeDataString(("principalId eq '{0}'" -f $ObjectId)) }
|    elseif ($explicitScope) { $path += '?$filter=' + [uri]::EscapeDataString('atScope()') }
|    $items = @(Invoke-SIArm -Path $path -ApiVersion '2022-04-01' -List)
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    # names only, built-ins read once per run (Get-SIAzRestRoleDefinitionNames) -- never the whole definition list per scope
|    $defs = Get-SIAzRestRoleDefinitionNames -Scope $subScope
|    $names = Resolve-SIAzRestPrincipalNames -Ids @($items | ForEach-Object { [string]$_.properties.principalId })
|    foreach ($a in $items) {
|        $rdId = ([string]$a.properties.roleDefinitionId -split '/')[-1]
|        $rdKey = $rdId.ToLowerInvariant()
|        $rdName = if ($defs.BuiltIn.ContainsKey($rdKey)) { $defs.BuiltIn[$rdKey] } else { $defs.Custom[$rdKey] }
|        if ($RoleDefinitionName -and $rdName -ne $RoleDefinitionName) { continue }
|        $oid = [string]$a.properties.principalId
|        [pscustomobject]@{
|            RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = [string]$a.properties.scope
|            DisplayName = $(if ($names.ContainsKey($oid)) { $names[$oid] } else { $null }); SignInName = $null
|            RoleDefinitionName = $rdName; RoleDefinitionId = $rdId; ObjectId = $oid; ObjectType = [string]$a.properties.principalType
|            CanDelegate = $false; Condition = $a.properties.condition; Description = [string]$a.properties.description
|        }
|    }
|}
|
|function New-SIAzRoleAssignmentRest {
|    # -Description (optional): stored on the assignment itself -- who gave it and why survives on Azure's side, so a later
|    # run can find an assignment it gave even when its own record of that is gone
|    [CmdletBinding()] param([string]$ObjectId, [string]$Scope, [string]$RoleDefinitionName, [string]$Description)
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    $def = @(Get-SIAzRestRoleDefinitions -Scope $subScope | Where-Object { [string]$_.properties.roleName -eq $RoleDefinitionName }) | Select-Object -First 1
|    if (-not $def) { throw ("The role definition '{0}' was not found at scope '{1}'." -f $RoleDefinitionName, $subScope) }
|    $name = [guid]::NewGuid().ToString()
|    $body = @{ properties = @{ roleDefinitionId = [string]$def.id; principalId = $ObjectId } }
|    if ("$Description".Trim()) { $body.properties['description'] = "$Description".Trim() }
|    $a = Invoke-SIArm -Method PUT -Path ($Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments/' + $name) -ApiVersion '2022-04-01' -Body $body
|    return [pscustomobject]@{ RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = $Scope; RoleDefinitionName = $RoleDefinitionName; RoleDefinitionId = [string]$def.name; ObjectId = $ObjectId; ObjectType = [string]$a.properties.principalType }
|}
|
|function Get-SIAzTagRest {
|    [CmdletBinding()] param([string]$ResourceId)
|    $t = Invoke-SIArm -Path ($ResourceId.TrimEnd('/') + '/providers/Microsoft.Resources/tags/default') -ApiVersion '2021-04-01'
|    $h = @{}
|    if ($t -and $t.properties -and $t.properties.tags) { foreach ($p in $t.properties.tags.PSObject.Properties) { $h[$p.Name] = [string]$p.Value } }
|    return [pscustomobject]@{ Id = [string]$t.id; Name = 'default'; Properties = [pscustomobject]@{ TagsProperty = $h } }
|}
|
|function Update-SIAzTagRest {
|    [CmdletBinding()] param([string]$ResourceId, [hashtable]$Tag, [string]$Operation = 'Merge')
|    if (-not $Operation) { $Operation = 'Merge' }
|    $t = Invoke-SIArm -Method PATCH -Path ($ResourceId.TrimEnd('/') + '/providers/Microsoft.Resources/tags/default') -ApiVersion '2021-04-01' -Body @{ operation = $Operation; properties = @{ tags = $Tag } }
|    $h = @{}
|    if ($t -and $t.properties -and $t.properties.tags) { foreach ($p in $t.properties.tags.PSObject.Properties) { $h[$p.Name] = [string]$p.Value } }
|    return [pscustomobject]@{ Id = [string]$t.id; Name = 'default'; Properties = [pscustomobject]@{ TagsProperty = $h } }
|}
|
|function Get-SIAzADServicePrincipalRest {
|    [CmdletBinding()] param([string]$ApplicationId, [string]$ObjectId)
|    $uri = if ($ObjectId) { 'https://graph.microsoft.com/v1.0/servicePrincipals/{0}?$select=id,appId,displayName,servicePrincipalNames' -f $ObjectId }
|           else { 'https://graph.microsoft.com/v1.0/servicePrincipals?$filter={0}&$select=id,appId,displayName,servicePrincipalNames' -f [uri]::EscapeDataString(("appId eq '{0}'" -f $ApplicationId)) }
|    $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience Graph -AllowNotFound -What 'Microsoft Graph service principal'
|    if (-not $r) { return }
|    $j = $r.Content | ConvertFrom-Json
|    $items = if ($j.PSObject.Properties['value']) { @($j.value) } else { @($j) }
|    foreach ($s in $items) { if ($s) { [pscustomobject]@{ Id = [string]$s.id; AppId = [string]$s.appId; DisplayName = [string]$s.displayName; ServicePrincipalName = @($s.servicePrincipalNames) } } }
|}
|
|function ConvertTo-SIAzDceObject {
|    param($D)
|    [pscustomobject]@{
|        Name = [string]$D.name; Id = [string]$D.id; Location = [string]$D.location
|        LogIngestionEndpoint = [string]$D.properties.logsIngestion.endpoint; ConfigurationAccessEndpoint = [string]$D.properties.configurationAccess.endpoint
|        NetworkAclsPublicNetworkAccess = [string]$D.properties.networkAcls.publicNetworkAccess; ProvisioningState = [string]$D.properties.provisioningState
|    }
|}
|
|function Get-SIAzDataCollectionEndpointRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($Name -and $ResourceGroupName) {
|        $d = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints/$Name") -ApiVersion '2022-06-01' -AllowNotFound
|        if (-not $d) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The data collection endpoint '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzDceObject $d)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints" } else { "/subscriptions/$sub/providers/Microsoft.Insights/dataCollectionEndpoints" }
|    foreach ($d in @(Invoke-SIArm -Path $path -ApiVersion '2022-06-01' -List)) { if (-not $Name -or [string]$d.name -eq $Name) { ConvertTo-SIAzDceObject $d } }
|}
|
|function New-SIAzDataCollectionEndpointRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName, [string]$Location, [string]$NetworkAclsPublicNetworkAccess = 'Enabled')
|    if (-not $NetworkAclsPublicNetworkAccess) { $NetworkAclsPublicNetworkAccess = 'Enabled' }
|    $sub = Get-SIAzRestSubscriptionId
|    $d = Invoke-SIArm -Method PUT -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints/$Name") -ApiVersion '2022-06-01' `
|             -Body @{ location = $Location; properties = @{ networkAcls = @{ publicNetworkAccess = $NetworkAclsPublicNetworkAccess } } }
|    return (ConvertTo-SIAzDceObject $d)
|}
|
|function Get-SIAzDataCollectionRuleRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName)
|    $sub = Get-SIAzRestSubscriptionId
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionRules" } else { "/subscriptions/$sub/providers/Microsoft.Insights/dataCollectionRules" }
|    foreach ($d in @(Invoke-SIArm -Path $path -ApiVersion '2022-06-01' -List)) {
|        if ($Name -and [string]$d.name -ne $Name) { continue }
|        [pscustomobject]@{ Name = [string]$d.name; Id = [string]$d.id; Location = [string]$d.location; ImmutableId = [string]$d.properties.immutableId; DataCollectionEndpointId = [string]$d.properties.dataCollectionEndpointId }
|    }
|}
|
|function New-SIAzStorageContextRest {
|    <# The storage "context" the REST path needs: the account name (and its endpoints). Every call
|       signs in with the run's identity (OAuth); there is no account-key form. #>
|    [CmdletBinding()] param([string]$StorageAccountName, [switch]$UseConnectedAccount)
|    return [pscustomobject]@{
|        PSTypeName = 'SI.AzRest.StorageContext'; SIRest = $true; StorageAccountName = $StorageAccountName
|        BlobEndPoint = ('https://{0}.blob.core.windows.net/' -f $StorageAccountName)
|        QueueEndPoint = ('https://{0}.queue.core.windows.net/' -f $StorageAccountName)
|        TableEndPoint = ('https://{0}.table.core.windows.net/' -f $StorageAccountName)
|    }
|}
|
|function Get-SIAzRestStorageAccountName {
|    param($Context)
|    if ($null -eq $Context) { throw 'No storage context was given.' }
|    $n = [string]$Context.StorageAccountName
|    if (-not $n) { throw 'The storage context does not name a storage account.' }
|    return $n
|}
|
|function ConvertTo-SIAzStorageAccountObject {
|    param($S)
|    $rg = if ([string]$S.id -match '/resourceGroups/([^/]+)/') { $Matches[1] } else { $null }
|    [pscustomobject]@{
|        StorageAccountName = [string]$S.name; ResourceGroupName = $rg; Id = [string]$S.id; Location = [string]$S.location
|        Kind = [string]$S.kind; Sku = $S.sku; PrimaryEndpoints = $S.properties.primaryEndpoints; ProvisioningState = [string]$S.properties.provisioningState
|        Context = (New-SIAzStorageContextRest -StorageAccountName ([string]$S.name) -UseConnectedAccount)
|    }
|}
|
|function Get-SIAzStorageAccountRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($ResourceGroupName -and $Name) {
|        $s = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$Name") -ApiVersion '2023-01-01' -AllowNotFound
|        if (-not $s) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The storage account '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzStorageAccountObject $s)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts" } else { "/subscriptions/$sub/providers/Microsoft.Storage/storageAccounts" }
|    foreach ($s in @(Invoke-SIArm -Path $path -ApiVersion '2023-01-01' -List)) { if (-not $Name -or [string]$s.name -eq $Name) { ConvertTo-SIAzStorageAccountObject $s } }
|}
|
|function Get-SIStorageAccountCreateProperties {
|    <#
|        PURE. The properties EVERY storage account SecurityInsight creates gets: shared-key access OFF (no account key
|        and no key-signed SAS works -- a user-delegation SAS still does), Entra ID the default in the portal, HTTPS only,
|        TLS 1.2 at least, no public blob access. Every SecurityInsight host reaches its storage with its own identity
|        (Storage Blob / Queue / Table Data roles), so nothing needs a key. An EXISTING account is never changed here;
|        setup\Set-SIStorageSharedKey.ps1 -Disable switches one off after checking nothing still uses a key.
|    #>
|    return @{
|        supportsHttpsTrafficOnly     = $true
|        allowBlobPublicAccess        = $false
|        allowSharedKeyAccess         = $false
|        defaultToOAuthAuthentication = $true
|        minimumTlsVersion            = 'TLS1_2'
|    }
|}
|
|function New-SIAzStorageAccountRest {
|    [CmdletBinding()]
|    param([string]$ResourceGroupName, [string]$Name, [string]$Location, [string]$SkuName, [string]$Kind, [bool]$EnableHttpsTrafficOnly = $true,
|          [string]$MinimumTlsVersion, [bool]$AllowBlobPublicAccess = $false,
|          # #866 (a private install): 'Disabled' CREATES the account with no public access -- only its private endpoints
|          [ValidateSet('', 'Disabled')][string]$PublicNetworkAccess = '')
|    $sub = Get-SIAzRestSubscriptionId
|    # -EnableHttpsTrafficOnly / -MinimumTlsVersion / -AllowBlobPublicAccess keep the Az cmdlet's shape, but a NEW
|    # account is always created locked down (Get-SIStorageAccountCreateProperties): no caller can weaken it.
|    $props = Get-SIStorageAccountCreateProperties
|    if ($PublicNetworkAccess -eq 'Disabled') { $props['publicNetworkAccess'] = 'Disabled' }
|    $path = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$Name"
|    $null = Invoke-SIArm -Method PUT -Path $path -ApiVersion '2023-01-01' -Body @{ location = $Location; sku = @{ name = $SkuName }; kind = $Kind; properties = $props }
|    # the create is asynchronous: wait until the account is THERE AND PROVISIONED (10 minutes at most) -- what follows
|    # (its roles, its containers) is refused "operation in progress" on an account Azure is still making. A "not found"
|    # in between is "not yet"; an account that is not ready in time is a clear stop, never handed on as if it were.
|    $s = $null; $state = ''
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    for ($i = 0; $i -lt 120; $i++) {
|        $s = Invoke-SIArm -Path $path -ApiVersion '2023-01-01' -AllowNotFound
|        $state = if ($s -and $s.properties) { [string]$s.properties.provisioningState } else { '' }
|        if ($s -and ($state -eq 'Succeeded' -or -not $state)) { return (ConvertTo-SIAzStorageAccountObject $s) }
|        if ($state -in 'Failed', 'Canceled') { throw ("The storage account '{0}' was not created: Azure reports it {1} -- see the activity log of resource group '{2}' for its reason." -f $Name, $state, $ResourceGroupName) }
|        if ($sleep -is [scriptblock]) { & $sleep 5 } else { Start-Sleep -Seconds 5 }
|    }
|    if (-not $s) { throw ("The storage account '{0}' was requested but did not appear." -f $Name) }
|    throw ("The storage account '{0}' is not ready 10 minutes after it was created (Azure shows: {1})." -f $Name, $(if ($state) { $state } else { 'no state' }))
|}
|
|function Get-SIAzStorageContainerRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $c = Test-SIBlobContainer -Account $acct -Container $Name
|    if (-not $c) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find the container '{0}' (ContainerNotFound)." -f $Name) -Target $Name; return }
|    return $c
|}
|
|function New-SIAzStorageContainerRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context, [string]$Permission)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    return (New-SIBlobContainer -Account $acct -Container $Name)
|}
|
|function ConvertTo-SIAzBlobObject {
|    <# A blob shaped like Get-AzStorageBlob's: Name / Length / LastModified / ETag, and the ICloudBlob members the call
|       sites read (Name, Container.Name, Properties.ETag / LastModified / Length). #>
|    param($B, [string]$Account)
|    $cloud = [pscustomobject]@{
|        Name = $B.Name; SIAccount = $Account
|        Container = [pscustomobject]@{ Name = $B.Container }
|        Properties = [pscustomobject]@{ ETag = $B.ETag; LastModified = $B.LastModified; Length = $B.Length; ContentType = $B.ContentType }
|    }
|    [pscustomobject]@{ Name = $B.Name; Length = $B.Length; LastModified = $B.LastModified; ETag = $B.ETag; ContentType = $B.ContentType; BlobType = 'BlockBlob'; ICloudBlob = $cloud }
|}
|
|function Get-SIAzStorageBlobRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [string]$Prefix, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if ($Blob) {
|        $b = Get-SIBlobProperties -Account $acct -Container $Container -Blob $Blob
|        if (-not $b) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find blob '{0}' in container '{1}' (BlobNotFound)." -f $Blob, $Container) -Target $Blob; return }
|        return (ConvertTo-SIAzBlobObject $b $acct)
|    }
|    foreach ($b in @(Get-SIBlobList -Account $acct -Container $Container -Prefix $Prefix)) { ConvertTo-SIAzBlobObject $b $acct }
|}
|
|function Get-SIAzStorageBlobContentRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [object]$CloudBlob, [string]$Destination, [object]$Context, [switch]$Force)
|    if ($CloudBlob) { $Blob = [string]$CloudBlob.Name; $Container = [string]$CloudBlob.Container.Name }
|    $acct = if ($Context) { Get-SIAzRestStorageAccountName -Context $Context } else { [string]$CloudBlob.SIAccount }
|    $target = $Destination
|    if (-not $target) { $target = (Get-Location).Path }
|    if (Test-Path -LiteralPath $target -PathType Container) { $target = [System.IO.Path]::Combine($target, ($Blob -replace '/', [System.IO.Path]::DirectorySeparatorChar)) }
|    $dir = Split-Path -Parent $target
|    if ($dir -and -not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
|    $null = Get-SIBlobContent -Account $acct -Container $Container -Blob $Blob -Destination $target
|    $b = Get-SIBlobProperties -Account $acct -Container $Container -Blob $Blob
|    if ($b) { return (ConvertTo-SIAzBlobObject $b $acct) }
|}
|
|function Set-SIAzStorageBlobContentRest {
|    [CmdletBinding()] param([string]$File, [string]$Container, [string]$Blob, [object]$Context, [switch]$Force)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if (-not $Blob) { $Blob = Split-Path -Leaf $File }
|    $etag = Set-SIBlobContent -Account $acct -Container $Container -Blob $Blob -File $File
|    $len = (Get-Item -LiteralPath $File).Length
|    return (ConvertTo-SIAzBlobObject ([pscustomobject]@{ Name = $Blob; Container = $Container; Length = $len; LastModified = [DateTimeOffset]::UtcNow; ETag = $etag; ContentType = 'application/octet-stream' }) $acct)
|}
|
|function Remove-SIAzStorageBlobRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [object]$Context, [switch]$Force)
|    Remove-SIBlob -Account (Get-SIAzRestStorageAccountName -Context $Context) -Container $Container -Blob $Blob
|}
|
|function Start-SIAzStorageBlobCopyRest {
|    <# A copy within the account: download and upload (the files SI copies are small exports), so no SAS and no
|       copy-source authorization is needed. #>
|    [CmdletBinding()] param([string]$SrcContainer, [string]$SrcBlob, [string]$DestContainer, [string]$DestBlob, [object]$Context, [switch]$Force)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $bytes = Get-SIBlobContent -Account $acct -Container $SrcContainer -Blob $SrcBlob
|    $null = Set-SIBlobContent -Account $acct -Container $DestContainer -Blob $DestBlob -Bytes $bytes
|    return [pscustomobject]@{ Name = $DestBlob; Container = $DestContainer }
|}
|
|function New-SIAzQueueObject {
|    <# A queue shaped like Get-AzStorageQueue's: .QueueClient with SendMessage / ReceiveMessage / DeleteMessage, as the
|       worker queue calls them. #>
|    param([string]$Account, [string]$Name)
|    $client = [pscustomobject]@{ Name = $Name; SIAccount = $Account }
|    $client | Add-Member -MemberType ScriptMethod -Name SendMessage -Value { param($Text) Send-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -Text ([string]$Text) }
|    $client | Add-Member -MemberType ScriptMethod -Name ReceiveMessage -Value {
|        param($VisibilityTimeout)
|        $secs = if ($VisibilityTimeout -is [timespan]) { [int]$VisibilityTimeout.TotalSeconds } elseif ($VisibilityTimeout) { [int]$VisibilityTimeout } else { 30 }
|        [pscustomobject]@{ Value = (Receive-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -VisibilityTimeoutSeconds $secs) }
|    }
|    $client | Add-Member -MemberType ScriptMethod -Name DeleteMessage -Value { param($Id, $PopReceipt) Remove-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -MessageId ([string]$Id) -PopReceipt ([string]$PopReceipt) }
|    return [pscustomobject]@{ Name = $Name; QueueClient = $client }
|}
|
|function Get-SIAzStorageQueueRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if (-not (Test-SIQueue -Account $acct -Queue $Name)) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find queue '{0}' (QueueNotFound)." -f $Name) -Target $Name; return }
|    return (New-SIAzQueueObject -Account $acct -Name $Name)
|}
|
|function New-SIAzStorageQueueRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    New-SIQueue -Account $acct -Queue $Name
|    return (New-SIAzQueueObject -Account $acct -Name $Name)
|}
|
|# #639 lane 4: a read in parts when one answer cannot carry it (Read-SILaParts) -- for every reader of a large result.
|# Loaded LAST: it reads through this file's Invoke-SIAzOperationalInsightsQuery (and loads this file itself when it is
|# dot-sourced alone, guarded on Invoke-SIArm -- defined by now, so never twice).
|if (-not (Get-Command -Name Read-SILaParts -ErrorAction Ignore)) {
|    $__siLaParts = [System.IO.Path]::Combine($PSScriptRoot, 'SI-LaParts.ps1')
|    if ([System.IO.File]::Exists($__siLaParts)) { . $__siLaParts }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LaStreamRead.ps1'] = @{ Sha256 = '76262967b7a09e5713b4687cf62f9267864ddcc0f3f11e678958f17226738511'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- A LOG ANALYTICS ANSWER READ AS IT ARRIVES, NEVER HELD WHOLE (Risk Analysis' lookups and answers;
|    owner rule "same method, all sizes; stream always").
|
|    The lean read (#639, SI-AzRest.ps1 ConvertFrom-SILaQueryRows) reads the answer's BYTES into one array of their full
|    length, parses them into a JsonDocument (an index of every token beside them), and only then builds the rows -- so
|    while a lookup is read the process holds the whole answer about three times (bytes + index + rows). A Risk Analysis
|    lookup at a large install is a tenant-sized answer (the identity CI lookup of a 153,000-user tenant: every key of every
|    identity), read in parts of up to the service's own answer limit; the large install's Risk Analysis job ran out of
|    memory on 2 CPU / 4 GiB (#730).
|
|    Here the response stream is read through a small buffer: each ROW is parsed when its bytes are in, turned into the row
|    object at once, and its bytes are let go. Only the rows are held -- the same rows the lean read builds: the same
|    columns in the same order, the same TEXT values (strings as sent, numbers in the service's own spelling, true / false,
|    null stays null, a nested value as its raw JSON text), the table named PrimaryResult else the first, the column list
|    (name / type) and the partial-error object. Compact rows (SI_LaCompactRows, Get-SILaCompactRowType) when the caller
|    asks for them, PSCustomObject rows otherwise.
|
|    pwsh 7 only (System.Text.Json's Utf8JsonReader, compiled once per process with Add-Type). Windows PowerShell, or a
|    process where the reader cannot be compiled: Get-SILaStreamReaderType answers $null and the caller keeps the lean read.
|
|    #836 (found 2026-10-20): NOTHING HERE LIVES ONLY IN THIS FILE'S SCRIPT SCOPE. A function reads $script: of its CALLER's
|    script, and in a container the entry point (container\Start-SIInContainer.ps1) dot-sources SI-AzRest.ps1 -> this file
|    in ITS scope while every engine runs as its own script and skips reloading it -- so a $script: source was $null there,
|    Add-Type failed, the failure was swallowed and no container engine ever streamed. The C# source comes from a FUNCTION
|    (Get-SILaStreamReaderSource), the compiled type is found by its name, and the state a run must share (the reader is off
|    and why, the last read's numbers) is $global:. The older read stays the fallback, but it is never silent: one plain line
|    on the run log says the older read is used and why (Write-SILaStreamFallback).
|#>
|
|function Get-SILaStreamReaderSource {
|    <# The reader's C# source. A FUNCTION, never a $script: variable (#836): callable from any script's scope. #>
|    @'
|using System;
|using System.Collections.Generic;
|using System.IO;
|using System.Management.Automation;
|using System.Reflection;
|using System.Text;
|using System.Text.Json;
|
|namespace SecurityInsight.LaStream
|{
|    public sealed class LaStreamAnswer
|    {
|        public object[] Rows { get; set; }
|        public string[] ColumnNames { get; set; }
|        public string[] ColumnTypes { get; set; }
|        public string ErrorJson { get; set; }
|        public long BytesRead { get; set; }
|        public int LargestBuffer { get; set; }
|        // with a page callback: the rows handed on and in how many pages (Rows is then empty)
|        public long RowsDelivered { get; set; }
|        public int Pages { get; set; }
|    }
|
|    // the caller's own page callback failed -- not a fault of the reader or of the answer
|    public sealed class LaStreamPageException : Exception
|    {
|        public LaStreamPageException(Exception inner) : base("the page callback failed: " + (inner == null ? "" : inner.Message), inner) { }
|    }
|
|    public static class LaStreamReader
|    {
|        // the rows handed on a page at a time: the table being handed on, the answer bytes of the rows waiting, the totals
|        private sealed class PageSink
|        {
|            public Action<object[]> On;
|            public long Limit;
|            public long Bytes;
|            public object Table;
|            public bool FromNonPrimary;
|            public long Rows;
|            public int Pages;
|        }
|
|        private static void Flush(PageSink sink, List<object> rows)
|        {
|            if (sink == null || rows == null || rows.Count == 0) { if (sink != null) sink.Bytes = 0; return; }
|            object[] page = rows.ToArray();
|            rows.Clear();
|            sink.Bytes = 0;
|            try { sink.On(page); }
|            catch (Exception e) { throw new LaStreamPageException(e); }
|            sink.Rows += page.Length;
|            sink.Pages++;
|        }
|
|        public static LaStreamAnswer Read(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor)
|        {
|            return Read(stream, compact, compactCtorFor, bufferSize, plainRowFor, null, 0);
|        }
|
|        // onPage: the primary table's rows are handed on a page at a time (about pageBytes of the answer each) and never
|        // collected; the answer's Rows is then empty, RowsDelivered / Pages say what was handed on
|        public static LaStreamAnswer Read(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor, Action<object[]> onPage, long pageBytes)
|        {
|            PageSink sink = onPage == null ? null : new PageSink { On = onPage, Limit = Math.Max(1024, pageBytes) };
|            return ReadCore(stream, compact, compactCtorFor, bufferSize, plainRowFor, sink);
|        }
|
|        private enum Ctx { Root, Tables, Table, Columns, Rows, Done }
|
|        private sealed class TableAcc
|        {
|            public int Index;
|            public string Name = "";
|            public List<string> Names = new List<string>();
|            public List<string> Types = new List<string>();
|            public bool ColumnsDone;
|            public bool Keep = true;
|            public ConstructorInfo Ctor;
|            public bool CtorAsked;
|            public Dictionary<string, string> Pool;
|            public List<object> Rows = new List<object>();
|            public List<string[]> Early;   // rows met before the column list (kept as values, built at the end)
|            public Func<string[], string[], object> Plain;   // names that differ only in case: the row is built as the lean read builds it
|            public bool PlainChecked;
|        }
|
|        private static LaStreamAnswer ReadCore(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor, PageSink sink)
|        {
|            if (stream == null) throw new ArgumentNullException("stream");
|            byte[] buf = new byte[Math.Max(1024, bufferSize)];
|            int filled = 0, start = 0;
|            bool final = false;
|            long total = 0;
|            int largest = buf.Length;
|            JsonReaderState state = new JsonReaderState();
|            var stack = new List<Ctx>();
|            string prop = null;
|            TableAcc cur = null, first = null, primary = null;
|            int tableCount = 0;
|            string errorJson = null;
|            bool bomChecked = false;
|
|            while (true)
|            {
|                // fill: keep what is not consumed, grow only when one unit does not fit
|                if (start > 0) { Buffer.BlockCopy(buf, start, buf, 0, filled - start); filled -= start; start = 0; }
|                if (!final)
|                {
|                    if (filled == buf.Length)
|                    {
|                        var bigger = new byte[buf.Length * 2]; Buffer.BlockCopy(buf, 0, bigger, 0, filled); buf = bigger;
|                        if (buf.Length > largest) largest = buf.Length;
|                    }
|                    int n = stream.Read(buf, filled, buf.Length - filled);
|                    if (n <= 0) final = true; else { filled += n; total += n; }
|                    if (!bomChecked && (filled >= 3 || final))
|                    {
|                        bomChecked = true;
|                        if (filled >= 3 && buf[0] == 0xEF && buf[1] == 0xBB && buf[2] == 0xBF) start = 3;
|                    }
|                    if (!final && filled < buf.Length && n > 0) continue;   // read until the buffer is full or the stream ends
|                }
|
|                var reader = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, start, filled - start), final, state);
|                bool more = false;
|                while (true)
|                {
|                    JsonReaderState before = reader.CurrentState;
|                    long beforeAt = reader.BytesConsumed;
|                    if (!reader.Read()) { more = true; break; }
|                    JsonTokenType tt = reader.TokenType;
|                    Ctx ctx = stack.Count == 0 ? Ctx.Root : stack[stack.Count - 1];
|                    if (stack.Count == 0)
|                    {
|                        if (tt == JsonTokenType.StartObject) { stack.Add(Ctx.Root); continue; }
|                        throw new JsonException("the Log Analytics answer is not a JSON object");
|                    }
|                    if (tt == JsonTokenType.PropertyName) { prop = reader.GetString(); continue; }
|
|                    // a UNIT: a value that is read whole (a row, a column, the error, anything skipped) -- its bytes must all be
|                    // in the buffer; when they are not, everything goes back to before its first token and more is read
|                    bool container = (tt == JsonTokenType.StartObject || tt == JsonTokenType.StartArray);
|                    switch (ctx)
|                    {
|                        case Ctx.Root:
|                            if (tt == JsonTokenType.EndObject) { stack[stack.Count - 1] = Ctx.Done; continue; }
|                            if (prop == "tables" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Tables); prop = null; continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (prop == "error")
|                                {
|                                    errorJson = (tt == JsonTokenType.Null) ? null : Encoding.UTF8.GetString(buf, us, ue - us);
|                                }
|                                prop = null;
|                                continue;
|                            }
|                        case Ctx.Tables:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); continue; }
|                            if (tt == JsonTokenType.StartObject)
|                            {
|                                cur = new TableAcc { Index = tableCount++, Plain = plainRowFor };
|                                // a later table's rows are kept only while no PrimaryResult was found before it
|                                cur.Keep = (primary == null);
|                                if (compact) cur.Pool = new Dictionary<string, string>(StringComparer.Ordinal);
|                                stack.Add(Ctx.Table); prop = null; continue;
|                            }
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            continue;
|                        case Ctx.Table:
|                            if (tt == JsonTokenType.EndObject)
|                            {
|                                stack.RemoveAt(stack.Count - 1);
|                                FinishTable(cur, compact, compactCtorFor);
|                                if (sink != null && object.ReferenceEquals(sink.Table, cur)) Flush(sink, cur.Rows);
|                                if (cur.Index == 0) first = cur;
|                                if (primary == null && cur.Name == "PrimaryResult") { primary = cur; if (first != null && first != cur) first.Rows = null; }
|                                else if (cur.Index != 0) cur.Rows = null;
|                                cur = null; prop = null; continue;
|                            }
|                            if (prop == "name" && !container)
|                            {
|                                cur.Name = (tt == JsonTokenType.String) ? (reader.GetString() ?? "") : "";
|                                prop = null; continue;
|                            }
|                            if (prop == "columns" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Columns); prop = null; continue; }
|                            if (prop == "rows" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Rows); prop = null; continue; }
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            prop = null; continue;
|                        case Ctx.Columns:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); cur.ColumnsDone = true; continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (tt == JsonTokenType.StartObject) ReadColumn(buf, us, ue - us, cur);
|                                continue;
|                            }
|                        case Ctx.Rows:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (tt == JsonTokenType.StartArray && cur.Keep)
|                                {
|                                    if (sink == null) AddRow(buf, us, ue - us, cur, compact, compactCtorFor);
|                                    else if (SinkTakes(sink, cur))
|                                    {
|                                        AddRow(buf, us, ue - us, cur, compact, compactCtorFor);
|                                        sink.Bytes += (ue - us);
|                                        if (sink.Bytes >= sink.Limit) Flush(sink, cur.Rows);
|                                    }
|                                }
|                                continue;
|                            }
|                        default:
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            continue;
|                    }
|                }
|                state = reader.CurrentState;
|                start += (int)reader.BytesConsumed;
|            Refill:
|                if (final)
|                {
|                    if (stack.Count == 0 || stack[0] != Ctx.Done) throw new JsonException("the Log Analytics answer ended before it was complete");
|                    break;
|                }
|                if (!more) continue;
|            }
|
|            TableAcc pick = primary ?? first;
|            var ans = new LaStreamAnswer { ErrorJson = errorJson, BytesRead = total, LargestBuffer = largest };
|            if (sink != null) { ans.RowsDelivered = sink.Rows; ans.Pages = sink.Pages; }
|            if (pick != null)
|            {
|                ans.Rows = (pick.Rows == null || sink != null) ? new object[0] : pick.Rows.ToArray();
|                ans.ColumnNames = pick.Names.ToArray();
|                ans.ColumnTypes = pick.Types.ToArray();
|            }
|            else { ans.Rows = new object[0]; ans.ColumnNames = new string[0]; ans.ColumnTypes = new string[0]; }
|            return ans;
|        }
|
|        // with a page callback: does this table's row go to the pages? The table named PrimaryResult, else the first table --
|        // as the whole read picks it. A PrimaryResult that comes after another table's rows were handed on cannot be read in
|        // pages (those rows are gone): the read fails, never a wrong set handed on.
|        private static bool SinkTakes(PageSink sink, TableAcc cur)
|        {
|            if (object.ReferenceEquals(sink.Table, cur)) return true;
|            if (sink.Table == null)
|            {
|                if (cur.Name == "PrimaryResult" || cur.Index == 0) { sink.Table = cur; sink.FromNonPrimary = (cur.Name != "PrimaryResult"); return true; }
|                return false;
|            }
|            if (cur.Name == "PrimaryResult" && sink.FromNonPrimary)
|            {
|                if (sink.Rows > 0) throw new InvalidOperationException("the Log Analytics answer names its primary table after another table whose rows were already handed on -- it cannot be read in pages");
|                ((TableAcc)sink.Table).Rows.Clear();
|                sink.Table = cur; sink.FromNonPrimary = false; sink.Bytes = 0;
|                return true;
|            }
|            return false;
|        }
|
|        private static void ReadColumn(byte[] buf, int off, int len, TableAcc t)
|        {
|            var r = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, off, len), true, new JsonReaderState());
|            r.Read();   // StartObject
|            string name = null, type = null; bool hasName = false;
|            while (r.Read())
|            {
|                if (r.TokenType == JsonTokenType.EndObject && r.CurrentDepth == 0) break;
|                if (r.TokenType != JsonTokenType.PropertyName) continue;
|                string p = r.GetString();
|                r.Read();
|                if (r.TokenType == JsonTokenType.StartObject || r.TokenType == JsonTokenType.StartArray) { r.Skip(); continue; }
|                if (p == "name") { name = (r.TokenType == JsonTokenType.String || r.TokenType == JsonTokenType.Null) ? r.GetString() : Encoding.UTF8.GetString(r.ValueSpan.ToArray()); hasName = true; }
|                else if (p == "type") { type = (r.TokenType == JsonTokenType.String || r.TokenType == JsonTokenType.Null) ? r.GetString() : Encoding.UTF8.GetString(r.ValueSpan.ToArray()); }
|            }
|            if (!hasName) throw new KeyNotFoundException("a column of the Log Analytics answer has no name");
|            t.Names.Add(name); t.Types.Add(type);
|        }
|
|        private static string[] ReadCells(byte[] buf, int off, int len, int nCols, Dictionary<string, string> pool)
|        {
|            var r = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, off, len), true, new JsonReaderState());
|            r.Read();   // StartArray
|            var cells = nCols >= 0 ? new string[nCols] : null;
|            var open = nCols < 0 ? new List<string>() : null;
|            int i = 0;
|            while (r.Read())
|            {
|                if (r.TokenType == JsonTokenType.EndArray && r.CurrentDepth == 0) break;
|                string s;
|                switch (r.TokenType)
|                {
|                    case JsonTokenType.String: s = r.GetString(); break;
|                    case JsonTokenType.Null: s = null; break;
|                    case JsonTokenType.True: s = "true"; break;
|                    case JsonTokenType.False: s = "false"; break;
|                    case JsonTokenType.StartObject:
|                    case JsonTokenType.StartArray:
|                        {
|                            int ts = (int)r.TokenStartIndex;
|                            r.Skip();
|                            s = Encoding.UTF8.GetString(buf, off + ts, (int)r.BytesConsumed - ts);
|                            break;
|                        }
|                    default: s = Encoding.UTF8.GetString(r.ValueSpan.ToArray()); break;
|                }
|                if (s != null && pool != null && s.Length <= 32)
|                {
|                    string p0;
|                    if (pool.TryGetValue(s, out p0)) s = p0; else pool[s] = s;
|                }
|                if (open != null) open.Add(s);
|                else if (i < nCols) cells[i] = s;
|                i++;
|            }
|            return open != null ? open.ToArray() : cells;
|        }
|
|        private static object MakeRow(string[] cells, TableAcc t)
|        {
|            if (t.Ctor != null) return t.Ctor.Invoke(new object[] { cells });
|            if (!t.PlainChecked)
|            {
|                t.PlainChecked = true;
|                var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase); bool dup = false;
|                foreach (var nm in t.Names) { if (nm != null && !seen.Add(nm)) { dup = true; break; } }
|                if (!dup) t.Plain = null;
|            }
|            if (t.Plain != null) return t.Plain(t.Names.ToArray(), cells);
|            var o = new PSObject();
|            int n = t.Names.Count;
|            for (int i = 0; i < n; i++)
|            {
|                string v = i < cells.Length ? cells[i] : null;
|                var existing = o.Properties[t.Names[i]];
|                if (existing != null) existing.Value = v; else o.Properties.Add(new PSNoteProperty(t.Names[i], v));
|            }
|            return o;
|        }
|
|        private static void AddRow(byte[] buf, int off, int len, TableAcc t, bool compact, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            if (!t.ColumnsDone && t.Names.Count == 0)
|            {
|                if (t.Early == null) t.Early = new List<string[]>();
|                t.Early.Add(ReadCells(buf, off, len, -1, null));
|                return;
|            }
|            if (compact && !t.CtorAsked) { MakeRowPrepare(t, compactCtorFor); }
|            var cells = ReadCells(buf, off, len, t.Names.Count, t.Ctor != null ? t.Pool : null);
|            t.Rows.Add(MakeRow(cells, t));
|        }
|
|        private static void MakeRowPrepare(TableAcc t, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            // the compact type for these columns, asked once; none -> PSCustomObject rows without pooling, as the lean read
|            t.CtorAsked = true;
|            if (compactCtorFor != null) t.Ctor = compactCtorFor(t.Names.ToArray());
|            if (t.Ctor == null) t.Pool = null;
|        }
|
|        private static void FinishTable(TableAcc t, bool compact, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            if (t.Early == null) return;
|            if (!t.Keep) { t.Early = null; return; }
|            var built = new List<object>(t.Early.Count + t.Rows.Count);
|            if (compact && !t.CtorAsked) MakeRowPrepare(t, compactCtorFor);
|            int n = t.Names.Count;
|            foreach (var raw in t.Early)
|            {
|                var cells = new string[n];
|                for (int i = 0; i < n && i < raw.Length; i++) cells[i] = raw[i];
|                built.Add(MakeRow(cells, t));
|            }
|            built.AddRange(t.Rows);
|            t.Rows = built; t.Early = null;
|        }
|    }
|}
|'@
|}
|
|function Get-SILaStreamReaderType {
|    <# The compiled reader ([SecurityInsight.LaStream.LaStreamReader]), built once per process; $null where it cannot be
|       (Windows PowerShell, or a compile that fails -- the caller then keeps the lean read). Scope-independent (#836): the
|       compiled type is found by its NAME (a type is per process), the source comes from a function, and a compile that
|       failed is remembered for the whole process in $global:SI_LaStreamReaderOff (its reason) -- tried once, not per read. #>
|    if ($PSVersionTable.PSEdition -ne 'Core') { return $null }
|    # off for this process (it could not be built, or it failed on an answer -- Read-SILaQueryStreamSafe): the older read
|    if ($global:SI_LaStreamReaderOff) { return $null }
|    $t = 'SecurityInsight.LaStream.LaStreamReader' -as [type]
|    if ($null -ne $t) { return $t }
|    try {
|        $src = Get-SILaStreamReaderSource
|        if ([string]::IsNullOrWhiteSpace([string]$src)) { throw 'its source is empty' }
|        Add-Type -TypeDefinition $src -Language CSharp -ErrorAction Stop
|        $t = 'SecurityInsight.LaStream.LaStreamReader' -as [type]
|        if ($null -eq $t) { throw 'the compiled type was not found' }
|        return $t
|    } catch {
|        $global:SI_LaStreamReaderOff = 'the reader could not be built in this process: ' + (Get-SILaStreamShortReason $_.Exception.Message)
|        return $null
|    }
|}
|
|function Get-SILaStreamShortReason {
|    <# PURE. The first line of an error text, at most 300 characters (a compiler error lists every line it refused). #>
|    param([AllowNull()][AllowEmptyString()][string]$Text)
|    $s = ([string]$Text -split "`r?`n" | Where-Object { $_.Trim() } | Select-Object -First 1)
|    if (-not $s) { return 'no reason given' }
|    $s = $s.Trim()
|    if ($s.Length -gt 300) { $s = $s.Substring(0, 300) + ' ...' }
|    return $s
|}
|
|function Write-SILaStreamFallback {
|    <#
|        #836: the older read is used instead of the streaming one -- ONE plain line on the run log (the transcript) saying
|        so and why. -Once: said once per process for that reason (the reader cannot be built: every later read is the
|        older one too, and saying it per read would flood the log). Without -Once (one read whose stream failed and was
|        read again the older way) it is said every time it happens. The results are the same either way.
|    #>
|    param([AllowNull()][AllowEmptyString()][string]$Reason, [switch]$Once)
|    if ([string]::IsNullOrWhiteSpace($Reason)) { $Reason = 'the streaming reader is not available in this process' }
|    if ($Once) {
|        if ($null -eq $global:SI_LaStreamFallbackSaid) { $global:SI_LaStreamFallbackSaid = @{} }
|        if ($global:SI_LaStreamFallbackSaid.ContainsKey($Reason)) { return }
|        $global:SI_LaStreamFallbackSaid[$Reason] = $true
|    }
|    Write-Host ('Log Analytics answers are read the older way (whole, then parsed) instead of as they arrive -- {0}. The rows are the same; the read uses more memory.' -f $Reason) -ForegroundColor DarkYellow
|}
|
|function Read-SILaQueryStreamSafe {
|    <#
|        #836: ConvertFrom-SILaQueryStream for Invoke-SILaQuery's -ReadStream -- DATA FIRST: a read that fails (the reader
|        throws, the answer is not valid JSON, the connection drops mid-answer) is NOT an error of the query: it answers a
|        marker (.SILaStreamFailed = why) and Invoke-SILaQuery reads the same query again the older way and says so in one
|        line. A failure that is not the network's (IOException / a socket error) turns streaming off for the rest of the
|        process ($global:SI_LaStreamReaderOff) so a reader fault never doubles every read.
|    #>
|    param([Parameter(Mandatory)][System.IO.Stream]$Stream, [switch]$Compact,
|          # the rows a page at a time (ConvertFrom-SILaQueryStream -OnPage); -PageState counts the pages handed on so far
|          [scriptblock]$OnPage, [long]$PageBytes = 4MB, [hashtable]$PageState)
|    try {
|        if ($OnPage) { return (ConvertFrom-SILaQueryStream -Stream $Stream -Compact:$Compact -OnPage $OnPage -PageBytes $PageBytes -PageState $PageState) }
|        return (ConvertFrom-SILaQueryStream -Stream $Stream -Compact:$Compact)
|    }
|    catch {
|        $ex = $_.Exception
|        # the CALLER's page callback failed (a page could not be stored): its own failure, passed on as it is -- never a
|        # reader fault, never read again
|        for ($e = $ex; $null -ne $e; $e = $e.InnerException) {
|            if ($e.GetType().FullName -eq 'SecurityInsight.LaStream.LaStreamPageException') {
|                $cause = $e.InnerException
|                while ($cause -is [System.Management.Automation.MethodInvocationException] -and $null -ne $cause.InnerException) { $cause = $cause.InnerException }
|                if ($cause -is [System.Management.Automation.RuntimeException] -and $cause.ErrorRecord) { throw $cause.ErrorRecord }
|                if ($null -ne $cause) { throw $cause }
|                throw $e
|            }
|        }
|        $net = $false
|        for ($e = $ex; $null -ne $e; $e = $e.InnerException) {
|            if ($e -is [System.IO.IOException] -or $e -is [System.Net.WebException] -or $e -is [System.Net.Sockets.SocketException]) { $net = $true; break }
|        }
|        $inner = $ex; while ($null -ne $inner.InnerException) { $inner = $inner.InnerException }
|        $why = Get-SILaStreamShortReason $inner.Message
|        if (-not $net) { $global:SI_LaStreamReaderOff = 'the streaming reader failed on an answer: ' + $why }
|        return [pscustomobject]@{ SILaStreamFailed = $why; Network = $net }
|    }
|}
|
|function ConvertFrom-SILaQueryStream {
|    <#
|        The Log Analytics query response READ FROM ITS STREAM -> @{ Rows; Columns; Error } -- the shape and the rows of
|        ConvertFrom-SILaQueryRows (SI-AzRest.ps1), without the answer ever being held whole. -Compact: compact rows
|        (Get-SILaCompactRowType) where a compact type can be built for the columns; PSCustomObject rows otherwise.
|        -BufferBytes: the first buffer (it grows only when one row does not fit). Throws on an answer that is not valid
|        JSON or ends early (as the lean read does).
|        -OnPage { param($Rows) }: FOR EVERY READER, not only Risk Analysis -- the primary table's rows are handed on a page
|        at a time, as soon as about -PageBytes of the answer's own bytes are in, and are never collected: memory is one
|        page. .Rows is then empty; .RowCount / .Pages say what was handed on; -PageState (a hashtable) is kept up to date
|        as pages go out (Pages, Rows). The error object (a cut answer) comes at the END of the answer, after the pages: a
|        caller keeps its pages only once the whole read returned (Invoke-SILaQuery -OnPage refuses a cut answer there).
|    #>
|    param([Parameter(Mandatory)][System.IO.Stream]$Stream, [switch]$Compact, [int]$BufferBytes = 65536,
|          [scriptblock]$OnPage, [long]$PageBytes = 4MB, [hashtable]$PageState)
|    $t = Get-SILaStreamReaderType
|    if ($null -eq $t) { throw 'the streaming Log Analytics reader is not available in this process' }
|    $ctorFor = $null
|    if ($Compact) {
|        $ctorFor = [Func[string[], System.Reflection.ConstructorInfo]] {
|            param([string[]]$names)
|            $ct = $null
|            if (Get-Command -Name Get-SILaCompactRowType -ErrorAction SilentlyContinue) { $ct = Get-SILaCompactRowType -Names $names }
|            if ($null -eq $ct) { return $null }
|            return $ct.GetConstructor([type[]]@([string[]]))
|        }
|    }
|    # column names that differ only in case (never in a real answer): the row is built exactly as the lean read builds it
|    # [[string[]]] -- the spelling Windows PowerShell 5.1 can parse too: setup scripts a customer runs there load this file
|    # through SI-AzRest.ps1 (the same type as [Func[string[], string[], object]], which 5.1 refuses as a parse error)
|    $plainFor = [Func[[string[]], [string[]], object]] {
|        param([string[]]$names, [string[]]$cells)
|        $o = [ordered]@{}
|        for ($i = 0; $i -lt $names.Length; $i++) { $o[$names[$i]] = $(if ($i -lt $cells.Length) { $cells[$i] } else { $null }) }
|        [pscustomobject]$o
|    }
|    if ($OnPage) {
|        if ($null -eq $PageState) { $PageState = @{} }
|        $PageState['Pages'] = 0; $PageState['Rows'] = 0L
|        $__psOn = $OnPage; $__psState = $PageState
|        $pageAction = [Action[object[]]] {
|            param([object[]]$page)
|            $null = & $__psOn $page
|            $__psState['Pages'] = [int]$__psState['Pages'] + 1
|            $__psState['Rows'] = [long]$__psState['Rows'] + $page.Length
|        }
|        $a = $t::Read($Stream, [bool]$Compact, $ctorFor, $BufferBytes, $plainFor, $pageAction, [long]$PageBytes)
|    } else {
|        $a = $t::Read($Stream, [bool]$Compact, $ctorFor, $BufferBytes, $plainFor)
|    }
|    $cols = [System.Collections.Generic.List[object]]::new()
|    for ($i = 0; $i -lt $a.ColumnNames.Length; $i++) { $cols.Add([pscustomobject]@{ name = $a.ColumnNames[$i]; type = $a.ColumnTypes[$i] }) }
|    $err = $null
|    if ($null -ne $a.ErrorJson) { $err = ($a.ErrorJson | ConvertFrom-Json) }
|    $count = [long]$a.Rows.Length; if ($OnPage) { $count = [long]$a.RowsDelivered }
|    # (#836: $global:, never $script: -- a function's $script: is its caller's)
|    $global:SI_LaStreamLast = [pscustomobject]@{ BytesRead = $a.BytesRead; LargestBuffer = $a.LargestBuffer; Rows = $count; Pages = [int]$a.Pages }
|    return [pscustomobject]@{ Rows = $a.Rows; Columns = $cols.ToArray(); Error = $err; RowCount = $count; Pages = [int]$a.Pages }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LaParts.ps1'] = @{ Sha256 = 'd6068eb409f171257cf45624fee0eea678cadb739bc63f8b366afc3f9b7b1edd'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- a Log Analytics read IN PARTS, so a large install never meets the service's limit on one answer
|    (#639 lane 4, owner 2026-10-21: "memory issues must not be a problem in any step. env must work in millions of assets
|    env"). Loaded by SI-AzRest.ps1, and guarded by every caller, so it loads on its own (tests).
|
|    WHY. One Log Analytics answer carries at most ~500,000 rows / ~64 MB. Invoke-SILaQuery REFUSES an answer the service
|    cut (New-SILaCutAnswerError) -- a cut answer is never taken as whole. A reader whose result can outgrow one answer
|    (a profile snapshot, the correlation map, a customer's rule query) therefore reads in PARTS:
|
|      * The query is first asked AS IT IS -- a small result costs exactly what it cost before (one query, unchanged).
|      * Refused as cut (or too large, or this process ran out of memory on it): the query is MEASURED once (rows and
|        bytes of its result) and read again in that many parts: each part is the query's own result, filtered on a hash
|        of each result row (or of a key the caller names). The parts never overlap and together are every row --
|        whatever the query does, because the filter is applied to its RESULT.
|      * A part still refused is cut in two (only that part; on a hash of its own, so the pieces never overlap); a part
|        far larger than planned cuts every part still to read by the measured factor. The size of a part follows what
|        was measured, never a fixed number (working rule 5).
|      * MEASURED stop, never a cap: a refused part that held NO row at all, twice in a row, is the query's own work
|        hitting a limit (every part repeats it) -- more parts cannot help, and the read fails saying so.
|      * A part that fails for any other reason fails THE READ: what was read is not the whole, so it is UNKNOWN -- never
|        handed out as the result (working rule 4). The caller's own handling of a failed read applies unchanged.
|
|    A query whose rows differ between two runs of it (take / limit / sample) is never cut into parts: its refusal is passed
|    on as it is. The rows of a read in parts come in no particular order.
|
|    PowerShell 5.1-safe: no ternary, no null-conditional. NO Set-StrictMode here (it leaks into the caller's scope).
|    A caller's -Read / -OnRows / -Log block runs INSIDE Read-SILaParts: a variable it reads must not share a name with
|    this function's own (Query, WorkspaceId, Wait, Key, Read, OnRows, What, Log, rows, got, page, queue ...).
|#>
|
|# Azure access: plain REST, no PowerShell modules (SI-AzRest.ps1 loads this file last, so this never loads it twice).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot './SI-AzRest.ps1') }
|
|function Get-SILaPartFilter {
|    <#
|        PURE. The KQL that keeps ONE part of a query's result: -Cuts = @( @{ Parts; Part } ...) -- the first cut is the
|        planned part ("bucket Part of Parts" of the row's hash); each later cut divides that part again on a hash of its own
|        (the depth in front of the value), so the pieces of a part never overlap and together are that part. -Key: a KQL
|        expression on the result's columns to hash (e.g. 'SI_AssetId'); '' = the whole result row (pack_all()). '' = no cut.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Cuts = @(), [string]$Key = '')
|    $terms = New-Object System.Collections.Generic.List[string]
|    for ($d = 0; $d -lt @($Cuts).Count; $d++) {
|        $parts = [long]$Cuts[$d].Parts; $part = [long]$Cuts[$d].Part
|        if ($parts -lt 1 -or $part -lt 0 -or $part -ge $parts) { throw ('Get-SILaPartFilter: part {0} is outside 0..{1}' -f $part, ($parts - 1)) }
|        if ($parts -eq 1) { continue }
|        if ($d -eq 0) { $terms.Add(('hash(_siPart, {0}) == {1}' -f $parts, $part)) }
|        else { $terms.Add(('hash(strcat("{0}|", _siPart), {1}) == {2}' -f $d, $parts, $part)) }
|    }
|    if ($terms.Count -eq 0) { return '' }
|    $k = 'tostring(pack_all())'
|    if ($Key) { $k = 'tostring({0})' -f $Key }
|    ('| extend _siPart = {0} | where {1} | project-away _siPart' -f $k, ($terms -join ' and '))
|}
|
|function Get-SILaPartQuery {
|    <#
|        PURE. -Query with -Filter after its LAST tabular statement: trailing blank / comment lines and semicolons are taken
|        off first, so the filter follows the result. '' -Filter = the query unchanged.
|    #>
|    param([Parameter(Mandatory)][string]$Query, [AllowEmptyString()][string]$Filter = '')
|    if (-not $Filter) { return $Query }
|    $lines = New-Object System.Collections.Generic.List[string]
|    foreach ($l in ($Query -split "`r?`n")) { $lines.Add($l) }
|    while ($lines.Count -gt 0) {
|        $t = $lines[$lines.Count - 1].Trim()
|        if ($t -eq '' -or $t.StartsWith('//')) { $lines.RemoveAt($lines.Count - 1); continue }
|        if ($t.EndsWith(';')) { $lines[$lines.Count - 1] = $lines[$lines.Count - 1].TrimEnd().TrimEnd(';'); continue }
|        break
|    }
|    (($lines -join "`n") + "`n" + $Filter)
|}
|
|function Get-SILaMeasureQuery {
|    <# PURE. How many rows -Query's result holds and about how many bytes (one small answer: SIRows, SIBytes). #>
|    param([Parameter(Mandatory)][string]$Query)
|    Get-SILaPartQuery -Query $Query -Filter '| summarize SIRows = count(), SIBytes = sum(estimate_data_size(*))'
|}
|
|function Test-SILaQueryPartable {
|    <# PURE. May -Query be read in parts? Not when its rows differ between two runs of it (take / limit / sample): the parts
|       of two runs would not be one result. #>
|    param([AllowEmptyString()][string]$Query)
|    -not ([string]$Query -match '(?im)\|\s*(take|limit|sample|sample-distinct)\b')
|}
|
|function Get-SILaPartFailure {
|    <#
|        PURE. What a failed read of one part says: @{ Cut = $true when a SMALLER part fixes it -- an answer the service cut
|        for a limit (Invoke-SILaQuery's refusal, Risk Analysis' own), an answer refused as too large, or this process out of
|        memory on it; Rows = the rows the short answer held (-1 unknown) }. Anything else: Cut = $false (passed on as it is).
|    #>
|    param([AllowNull()][object]$Err)
|    $ex = $null; $texts = New-Object System.Collections.Generic.List[string]
|    if ($Err -is [System.Management.Automation.ErrorRecord]) {
|        $ex = $Err.Exception
|        if ($Err.ErrorDetails -and $Err.ErrorDetails.Message) { $texts.Add([string]$Err.ErrorDetails.Message) }
|    } elseif ($Err -is [System.Exception]) { $ex = $Err }
|    elseif ($null -ne $Err) { $texts.Add([string]$Err) }
|    $e = $ex
|    while ($null -ne $e) {
|        if ($e -is [System.OutOfMemoryException] -or $e -is [System.InsufficientExecutionStackException]) { return @{ Cut = $true; Rows = -1L; Why = 'too large for this job''s memory' } }
|        if ($e.Data) {
|            foreach ($k in 'SILaPartial', 'SIRALaPartial') {
|                if ($e.Data.Contains($k)) {
|                    $rows = -1L
|                    if ($e.Data.Contains('SIRALaPartialRows')) { try { $rows = [long]$e.Data['SIRALaPartialRows'] } catch { $rows = -1L } }
|                    return @{ Cut = ([string]$e.Data[$k] -eq 'Limit'); Rows = $rows; Why = 'cut by the service''s limit' }
|                }
|            }
|        }
|        $texts.Add([string]$e.Message)
|        try { if ($e.PSObject.Properties['Response'] -and $e.Response -and $e.Response.PSObject.Properties['Content']) { $texts.Add([string]$e.Response.Content) } } catch { }
|        $e = $e.InnerException
|    }
|    $all = ($texts -join ' ')
|    if ($all -match '(?i)E_QUERY_RESULT_SET_TOO_LARGE|ResponsePayloadTooLarge|ResponseSizeError|result set (is )?too large|exceeds? the (maximum )?(response|result) size|response size .*exceed') {
|        return @{ Cut = $true; Rows = -1L; Why = 'too large to read in one answer' }
|    }
|    @{ Cut = $false; Rows = -1L; Why = '' }
|}
|
|function ConvertTo-SILaPartRows {
|    <# PURE. Rows however a reader handed them over -- one array (`, @(rows)`), an array holding that array, or rows on the
|       pipeline -- as ONE flat object[] without nulls. #>
|    param([AllowNull()][object]$Answer)
|    $l = New-Object System.Collections.Generic.List[object]
|    foreach ($x in @($Answer)) {
|        if ($null -eq $x) { continue }
|        if ($x -is [array]) { foreach ($y in $x) { if ($null -ne $y) { $l.Add($y) } } } else { $l.Add($x) }
|    }
|    , $l.ToArray()
|}
|
|function Get-SILaPartPlan {
|    <#
|        PURE. How many parts a result of -Rows rows / about -Bytes bytes is read in: each part well under one answer's
|        limits -- at most half the service's own row limit, and -TargetBytes of answer (the JSON answer is -Expansion times
|        the data's own size). At least 2 (the result was refused whole). Follows the measurement; no ceiling.
|    #>
|    param([long]$Rows = -1, [double]$Bytes = -1, [long]$TargetRows = 0, [double]$TargetBytes = 16MB, [double]$Expansion = 2.5)
|    if ($TargetRows -le 0) {
|        $limit = 500000L
|        if (Get-Command -Name Get-SILaServiceRowLimit -ErrorAction SilentlyContinue) { $limit = [long](Get-SILaServiceRowLimit) }
|        $TargetRows = [long][Math]::Max(1, [Math]::Floor($limit / 2))
|    }
|    $n = 2L
|    if ($Rows -gt 0) { $n = [long][Math]::Max($n, [Math]::Ceiling([double]$Rows / [double]$TargetRows)) }
|    if ($Bytes -gt 0 -and $TargetBytes -gt 0) { $n = [long][Math]::Max($n, [Math]::Ceiling(($Bytes * $Expansion) / $TargetBytes)) }
|    $n
|}
|
|function Read-SILaParts {
|    <#
|        ONE Log Analytics read, in parts when one answer cannot carry it (see the header of this file). Every row once.
|          -Query      the KQL (asked as it is first)
|          -Key        a KQL expression on the result's columns that the parts hash on ('' = the whole result row). A key
|                      that is the same for many rows cannot divide them -- '' always can.
|          -Read       { param($Kql) rows } -- the reader (the seam for tests). Default: Invoke-SIAzOperationalInsightsQuery
|                      on -WorkspaceId (with -Wait), its .Results.
|          -OnRows     { param($Rows) } -- each part's rows as soon as that part is read whole (then not collected; memory is
|                      one part). The parts handed on are only the result when this call RETURNS: a later part that fails
|                      throws, and the caller treats the whole read as failed. Without -OnRows the rows are collected.
|          -What       what is read, for the lines it says; -Log { param($Level, $Message) }
|        Returns @{ Rows (without -OnRows); RowCount; Pages; Parts (planned); Cuts }. Throws when the read is not whole.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Query,
|        [string]$WorkspaceId = '',
|        [int]$Wait = 0,
|        [string]$Key = '',
|        [scriptblock]$Read,
|        [scriptblock]$OnRows,
|        [string]$What = 'the Log Analytics read',
|        [scriptblock]$Log,
|        [long]$TargetRows = 0,
|        [double]$TargetBytes = 16MB,
|        [int]$MaxDepth = 24
|    )
|    if (-not $Read) {
|        if (-not $WorkspaceId) { throw 'Read-SILaParts: -WorkspaceId or -Read is needed' }
|        # (-Wait only when given: the same call the readers made before, so a reader's own stand-in still answers it)
|        $Read = {
|            param($k)
|            $__p = @{ WorkspaceId = $WorkspaceId; Query = $k; ErrorAction = 'Stop' }
|            if ($Wait -gt 0) { $__p['Wait'] = $Wait }
|            $__a = Invoke-SIAzOperationalInsightsQuery @__p
|            if ($__a) { , @($__a.Results) } else { , @() }
|        }
|    }
|    if (-not $Log) { $Log = { param($l, $m) Write-Host ('[{0}] {1}' -f $l, $m) } }
|    if ($TargetRows -le 0) {
|        $limit = 500000L
|        if (Get-Command -Name Get-SILaServiceRowLimit -ErrorAction SilentlyContinue) { $limit = [long](Get-SILaServiceRowLimit) }
|        $TargetRows = [long][Math]::Max(1, [Math]::Floor($limit / 2))
|    }
|    $partable = Test-SILaQueryPartable -Query $Query
|    $acc = $null
|    if (-not $OnRows) { $acc = New-Object System.Collections.Generic.List[object] }
|    $queue = New-Object 'System.Collections.Generic.Queue[object]'
|    $queue.Enqueue([pscustomobject]@{ Cuts = @() })
|    $pages = 0L; $rowsRead = 0L; $cutsMade = 0L; $planned = 1L; $measured = $false; $emptyRefusals = 0
|    while ($queue.Count -gt 0) {
|        $page = $queue.Dequeue()
|        $kql = Get-SILaPartQuery -Query $Query -Filter (Get-SILaPartFilter -Cuts @($page.Cuts) -Key $Key)
|        $rows = $null; $fail = $null
|        try {
|            # assigned first: the reader answers ONE array (`, @(rows)`) -- @() around the call would hold it as one row
|            $got = & $Read $kql
|            $rows = ConvertTo-SILaPartRows $got
|            $got = $null
|        } catch {
|            $f = Get-SILaPartFailure -Err $_
|            if (-not $f.Cut -or -not $partable) { throw }
|            $fail = $f; $failErr = $_
|        }
|        if ($fail) {
|            $rows = $null
|            if (@($page.Cuts).Count -ge $MaxDepth) {
|                throw ('{0} is more than Log Analytics can answer: a part cut {1} times is still {2} -- the read is not whole and nothing of it is used' -f $What, @($page.Cuts).Count, $fail.Why)
|            }
|            if ([long]$fail.Rows -eq 0) { $emptyRefusals++ } else { $emptyRefusals = 0 }
|            if ($emptyRefusals -ge 2) {
|                throw ('{0} is more than Log Analytics can answer: a part stopped at the service''s limit before it returned a row, twice, so reading it in more parts cannot make it fit -- the read is not whole and nothing of it is used ({1})' -f $What, (([string]$failErr.Exception.Message -split "`n") | Select-Object -First 1))
|            }
|            if (@($page.Cuts).Count -eq 0 -and -not $measured) {
|                # the whole query was refused: measured ONCE, then read in that many parts
|                $measured = $true
|                $mRows = -1L; $mBytes = -1.0
|                try {
|                    $mr = ConvertTo-SILaPartRows (& $Read (Get-SILaMeasureQuery -Query $Query)); $m = $null; if ($mr.Count -gt 0) { $m = $mr[0] }
|                    if ($m) {
|                        if ($m.PSObject.Properties['SIRows'] -and "$($m.SIRows)" -ne '') { $mRows = [long][double]::Parse([string]$m.SIRows, [Globalization.CultureInfo]::InvariantCulture) }
|                        if ($m.PSObject.Properties['SIBytes'] -and "$($m.SIBytes)" -ne '') { $mBytes = [double]::Parse([string]$m.SIBytes, [Globalization.CultureInfo]::InvariantCulture) }
|                    }
|                } catch { $mRows = -1L; $mBytes = -1.0 }
|                $planned = Get-SILaPartPlan -Rows $mRows -Bytes $mBytes -TargetRows $TargetRows -TargetBytes $TargetBytes
|                for ($p = 0L; $p -lt $planned; $p++) { $queue.Enqueue([pscustomobject]@{ Cuts = @([pscustomobject]@{ Parts = $planned; Part = $p }) }) }
|                $cutsMade++
|                $sizeText = ''
|                if ($mRows -ge 0) { $sizeText = [string]::Format([Globalization.CultureInfo]::InvariantCulture, ' (measured: {0:N0} row(s){1})', $mRows, $(if ($mBytes -ge 0) { [string]::Format([Globalization.CultureInfo]::InvariantCulture, ', about {0:N0} MB', ($mBytes / 1MB)) } else { '' })) }
|                & $Log 'INFO' ('{0} is larger than one Log Analytics answer can carry ({1}) -- it is read in {2} parts{3}; nothing of the short answer is kept' -f $What, $fail.Why, $planned, $sizeText)
|            } else {
|                foreach ($half in 0, 1) { $queue.Enqueue([pscustomobject]@{ Cuts = @($page.Cuts) + @([pscustomobject]@{ Parts = 2L; Part = [long]$half }) }) }
|                $cutsMade++
|                & $Log 'INFO' ('{0}: a part was {1} -- it is read again in two smaller parts' -f $What, $fail.Why)
|            }
|            continue
|        }
|        $emptyRefusals = 0
|        $n = $rows.Count
|        $pages++; $rowsRead += $n
|        if ($OnRows) { $null = & $OnRows $rows } else { $acc.AddRange([object[]]$rows) }
|        $rows = $null
|        # measured, not assumed: a part far larger than planned -> every part still to read is cut by that factor
|        if (@($page.Cuts).Count -gt 0 -and $n -gt (2 * $TargetRows) -and $queue.Count -gt 0) {
|            $factor = [long][Math]::Ceiling([double]$n / [double]$TargetRows)
|            $rest = $queue.ToArray(); $queue.Clear()
|            foreach ($rp in $rest) { for ($piece = 0L; $piece -lt $factor; $piece++) { $queue.Enqueue([pscustomobject]@{ Cuts = @($rp.Cuts) + @([pscustomobject]@{ Parts = $factor; Part = $piece }) }) } }
|            $cutsMade++
|            & $Log 'INFO' ('{0}: its parts are larger than measured -- the {1} part(s) still to read are read as {2}' -f $What, $rest.Count, $queue.Count)
|        }
|    }
|    if ($pages -gt 1) { & $Log 'INFO' ([string]::Format([Globalization.CultureInfo]::InvariantCulture, '{0}: read whole in {1} part(s), {2:N0} row(s)', $What, $pages, $rowsRead)) }
|    $out = [ordered]@{ Rows = @(); RowCount = $rowsRead; Pages = $pages; Parts = $planned; Cuts = $cutsMade }
|    if ($acc) { $out.Rows = $acc.ToArray() }
|    [pscustomobject]$out
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LogIngest.ps1'] = @{ Sha256 = '877c581ac6adda5fa7951afb09db3fefd7fbe77742dfbc686cf9037255224f6f'; Text = @'
|#Requires -Version 5.1
|<#
|    SI -- publish rows to a Log Analytics custom table through the normal DCR path.
|
|    Moved here from engine/asset-correlation/_shared/SI-CorrelationIngest.ps1 because a FREE stage uses
|    it too: the azure profiler's Defender for Cloud recommendations stage publishes with
|    Send-SIObjectMapRows. The correlation engine is part of SecurityInsight Pro and is not in the
|    Community edition, so a free engine must never load a file from its folder. The function names are
|    unchanged, so every caller and test keeps working.
|#>
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction Ignore)) { . (Join-Path $PSScriptRoot './SI-AzRest.ps1') }
|
|function Initialize-SIIngestGlobals {
|    <#
|      Fill the three names the DCR/DCE pinning and the LogIngest role grant need, from what an install
|      actually has (#174). The profiling orchestrator backfills them at its entry; the stages and engines that
|      publish WITHOUT it (trend, Defender recommendations, the Pro engines) did not -- and the CLI setup wrote
|      only the older names -- so pinning was skipped and a new DCR got no LogIngest principal.
|        SI_AzSubscriptionId  <- the subscription in SI_WorkspaceResourceId, else the 2.2.x SubscriptionId
|        SI_DceResourceGroup  <- the 2.2.x DceResourceGroup, else SI_DcrResourceGroup (same RG by default)
|        SI_SPN_ObjectId      <- SpnObjectId, else SI_LogIngest_ObjectId
|      Only EMPTY names are filled; a value the customer set always stands. Never throws.
|    #>
|    if (-not $global:SI_AzSubscriptionId) {
|        if ("$($global:SI_WorkspaceResourceId)" -match '/subscriptions/([^/]+)/') { $global:SI_AzSubscriptionId = $Matches[1] }
|        elseif ($global:SubscriptionId) { $global:SI_AzSubscriptionId = [string]$global:SubscriptionId }
|    }
|    if (-not $global:SI_DceResourceGroup) {
|        # SI_DcrResourceGroup FIRST: the unprefixed DceResourceGroup is ALWAYS set by the solution-wide shared
|        # defaults ('rg-dce-securityinsight'), so after loading it cannot tell a customer value from the default.
|        # The DCE normally lives with the DCRs (the sample: "leave unset, same RG as workspace").
|        if ($global:SI_DcrResourceGroup) { $global:SI_DceResourceGroup = [string]$global:SI_DcrResourceGroup }
|        elseif ($global:DceResourceGroup) { $global:SI_DceResourceGroup = [string]$global:DceResourceGroup }
|    }
|    if (-not $global:SI_SPN_ObjectId) {
|        if ($global:SpnObjectId) { $global:SI_SPN_ObjectId = [string]$global:SpnObjectId }
|        elseif ($global:SI_LogIngest_ObjectId) { $global:SI_SPN_ObjectId = [string]$global:SI_LogIngest_ObjectId }
|    }
|}
|
|function Get-SILogIngestObjectId {
|    <#
|      The object id that gets the ingest role on a new or updated data collection rule: SI_SPN_ObjectId (what setup
|      writes), else the older SI_LogIngest_ObjectId -- the same order Send-SIObjectMapRows, trend, asset properties and
|      the run-health row use. Three output stages passed SI_LogIngest_ObjectId alone, so an install with only
|      SI_SPN_ObjectId got a rule nobody could post to (#257). Empty when neither is set.
|    #>
|    if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_SPN_ObjectId)) { return [string]$global:SI_SPN_ObjectId }
|    return [string]$global:SI_LogIngest_ObjectId
|}
|
|function Select-SIIngestTarget {
|    <#
|        #199 -- make the endpoint AzLogDcrIngestPS will use the RIGHT one, before it touches the rule and again
|        before the post. The module resolves the endpoint by NAME ONLY -- the first match in $global:AzDceDetails,
|        or in a tenant-wide Resource Graph query when that cache is empty. Measured 2026-10-01: three endpoints
|        named dce-securityinsight in two subscriptions; a rule created on the right one was re-bound to another
|        one minute later by the engine's own post (#198); four rules on this tenant were bound to the other
|        subscription's endpoint.
|        The endpoint is chosen as follows:
|          - a rule that EXISTS posts through the endpoint it is bound to, when that endpoint has the configured
|            name. Ingestion accepts a post only through the rule's own endpoint, and moving a rule is not an
|            option -- measured 2026-10-01, a re-bound rule was still refused (HTTP 403) more than 10 minutes later.
|          - otherwise (a new rule) this install's endpoint -- subscription + resource group + name -- so the
|            module creates the rule there and not on a same-named endpoint elsewhere.
|          - ONE endpoint of that name anywhere is unambiguous and used (an endpoint outside the rules' resource
|            group has always worked that way). Several and none here: refused, nothing is posted.
|        The DCR cache is narrowed to this install's rule (or, before it exists, cleared of same-named rules
|        elsewhere). An empty cache is built first. Without a subscription id there is nothing to pin to.
|    #>
|    param([hashtable]$AuthParams, [Parameter(Mandatory)][string]$DcrName)
|    $sub = [string]$global:SI_AzSubscriptionId
|    if (-not $sub -or -not $global:SI_DceName) { return }
|    $dceRg = if ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup } else { [string]$global:SI_DcrResourceGroup }
|    $dcrRg = [string]$global:SI_DcrResourceGroup
|    $rebuilt = $false
|    $rebuild = {
|        if ($rebuilt -or -not $AuthParams) { return }
|        try { $global:AzDceDetails = Get-SIDceList @AuthParams -Verbose:$false 4>$null } catch { }
|        try { $global:AzDcrDetails = Get-SIDcrList @AuthParams -Verbose:$false 4>$null } catch { }
|        $rebuilt = $true   # dot-sourced: this IS the function's scope
|    }
|    $findHere = { @($global:AzDceDetails | Where-Object { $_ -and $_.name -eq $global:SI_DceName -and [string]$_.id -like "/subscriptions/$sub/resourceGroups/$dceRg/*" }) | Select-Object -First 1 }
|    $findRule = { if ($dcrRg) { @($global:AzDcrDetails | Where-Object { $_ -and $_.name -eq $DcrName -and [string]$_.id -like "/subscriptions/$sub/resourceGroups/$dcrRg/*" }) | Select-Object -First 1 } }
|
|    if (-not $global:AzDceDetails) { . $rebuild }
|    $dce = . $findHere
|    $dcr = . $findRule
|    if (-not $dce -or ($dcrRg -and -not $dcr)) { . $rebuild; $dce = . $findHere; $dcr = . $findRule }
|    if (-not $dce) {
|        $same = @($global:AzDceDetails | Where-Object { $_ -and $_.name -eq $global:SI_DceName })
|        if ($same.Count -ne 1) {
|            throw ("Data collection endpoint '{0}' was not found in resource group '{1}' of subscription '{2}'. {3} endpoint(s) of that name exist elsewhere, so nothing was posted -- set SI_DceResourceGroup to the one this install uses." -f $global:SI_DceName, $dceRg, $sub, $same.Count)
|        }
|        $dce = $same[0]
|    }
|    $bound = if ($dcr -and $dcr.properties) { [string]$dcr.properties.dataCollectionEndpointId } else { '' }
|    if ($bound -and $bound -ne [string]$dce.id) {
|        $b = @($global:AzDceDetails | Where-Object { $_ -and [string]$_.id -eq $bound }) | Select-Object -First 1
|        if (-not $b) { . $rebuild; $b = @($global:AzDceDetails | Where-Object { $_ -and [string]$_.id -eq $bound }) | Select-Object -First 1 }
|        if ($b -and $b.name -eq $global:SI_DceName) {
|            Write-Verbose ("Data collection rule '{0}' is bound to {1}; posting through it." -f $DcrName, $bound)
|            $dce = $b
|        }
|    }
|    $global:AzDceDetails = @($dce)
|    if ($dcr) { $global:AzDcrDetails = @($dcr) }
|    elseif ($global:AzDcrDetails) { $global:AzDcrDetails = @($global:AzDcrDetails | Where-Object { $_ -and $_.name -ne $DcrName }) }
|}
|function Resolve-SICorrelationAuthParams {
|    <#
|        MI > SPN+cert > SPN+secret, resolved into the splat AzLogDcrIngestPS wants.
|        Mirrors Send-SIRunHealthRow deliberately -- see this file's header for why it is not shared.
|    #>
|    $spnAppId     = if ($global:SI_SPN_AppId)    { $global:SI_SPN_AppId }    else { $global:SI_LogIngest_AppId }
|    $spnSecret    = if ($global:SI_SPN_Secret)   { $global:SI_SPN_Secret }   else { $global:SI_LogIngest_Secret }
|    $spnTenantId  = if ($global:SI_SPN_TenantId) { $global:SI_SPN_TenantId } else { $global:SI_LogIngest_TenantId }
|    $spnCertThumb = [string]$global:SI_SPN_CertThumbprint
|
|    # Auto-detect which store actually holds the private key. A thumbprint in the wrong store reads as
|    # "no cert" and falls through to the secret branch, which then fails on a tenant that has no secret.
|    $spnCertStore = if ($global:SI_SPN_CertStoreLocation) { [string]$global:SI_SPN_CertStoreLocation }
|                    elseif ($spnCertThumb) {
|                        $clean = $spnCertThumb -replace '\s',''
|                        if (Get-PSDrive -Name Cert -ErrorAction SilentlyContinue) {
|                            $resolved = 'LocalMachine'
|                            foreach ($s in 'LocalMachine','CurrentUser') {
|                                $c = Get-ChildItem "Cert:\$s\My" -ErrorAction SilentlyContinue |
|                                     Where-Object { $_.Thumbprint -eq $clean -and $_.HasPrivateKey } |
|                                     Select-Object -First 1
|                                if ($c) { $resolved = $s; break }
|                            }
|                            $resolved
|                        } else {
|                            # #209: no Cert: drive (a Linux container) -- read the X509Store instead.
|                            if (-not (Get-Command Get-SICertStoreLocation -ErrorAction Ignore)) {
|                                . (Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth/Find-SICertificate.ps1')
|                            }
|                            Get-SICertStoreLocation -Thumbprint $clean
|                        }
|                    } else { 'LocalMachine' }
|
|    $useMi   = $global:SI_PreferUami -and -not [string]::IsNullOrWhiteSpace($global:SI_UAMI_ClientId)
|    $useCert = -not $useMi -and -not [string]::IsNullOrWhiteSpace($spnCertThumb)
|
|    if ($useMi) {
|        return @{ UseManagedIdentity = $true; ManagedIdentityClientId = $global:SI_UAMI_ClientId }
|    }
|    if ($useCert) {
|        return @{
|            AzAppId                       = $spnAppId
|            AzAppCertificateThumbprint    = $spnCertThumb
|            AzAppCertificateStoreLocation = $spnCertStore
|            TenantId                      = $spnTenantId
|        }
|    }
|    @{ AzAppId = $spnAppId; AzAppSecret = $spnSecret; TenantId = $spnTenantId }
|}
|
|function Send-SIObjectMapRows {
|    <#
|        Publish the map to SI_ObjectMap_CL through the normal DCR path.
|
|        SQL COMPUTES AND HOLDS, LA PUBLISHES -- and there is no SQL yet, so today this IS the store.
|
|        🔴 CORRECTED 2026-08-13. This header used to say the deterministic seed means "an object's id is
|        recomputed identically every run", and that key-stability memory was "an OPTIMISATION over a
|        correctness property the core already has". THAT WAS WRONG, and believing it is what would ship
|        duplicate CIs. The property the core has is `same INPUT -> same id`. The property a connector
|        needs is `same OBJECT -> same id`. They diverge whenever group membership changes:
|
|          * Measured: adding one member carrying a lower-sorting exposure-graph id moved a group from
|            `exposuregraphnodeid:aaa` to `exposuregraphnodeid:000`. The seed is the ordinally-lowest
|            value of the highest-priority type PRESENT IN THE GROUP, so any arrival or departure moves
|            it.
|          * Departures are routine: the same day, EndpointEG returned 0 rows on a timeout and 51 assets
|            left the snapshot.
|          * Anchors churn independently -- MDE ids rotate, a rebuilt VM gets a new ARM path, a
|            re-enrolled device gets a new AadDeviceId.
|
|        So SQL key-stability is a CORRECTNESS PREREQUISITE before the connector may create CIs, not an
|        optimisation. Publishing to LA without it is fine -- reading a map is harmless. CREATING a
|        ServiceNow CI from an id that can move is not.
|
|        Decided 2026-08-13 (V3-ARCHITECTURE 2.3a): a minted UUIDv5-from-birth-anchor id, stored, with an
|        anchor ledger and a superseded table. Until that exists, ids emitted here are PROVISIONAL and a
|        connector must not create CIs from them.
|
|        NOT best-effort. Unlike the run-health heartbeat, this IS the output -- a swallowed failure
|        would leave consumers reading a stale map while every run reported success.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Rows,
|        [string]$TableName = 'SI_ObjectMap',
|        [string]$DcrName
|    )
|
|    if (@($Rows).Count -eq 0) {
|        Write-Warning 'correlation: nothing to publish -- 0 map rows. Not posting.'
|        return 0
|    }
|    if ([string]::IsNullOrWhiteSpace($DcrName)) {
|        $DcrName = if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_ObjectMap_DcrName)) {
|            [string]$global:SI_ObjectMap_DcrName
|        } else { 'dcr-si-objectmap' }
|    }
|
|    $savedVerbose = $global:VerbosePreference
|    $global:VerbosePreference = 'SilentlyContinue'
|    $lock = $null
|    try {
|        $authParams = Resolve-SICorrelationAuthParams
|        Initialize-SIIngestGlobals
|        $spnObjectId = if ($global:SI_SPN_ObjectId) { $global:SI_SPN_ObjectId } else { $global:SI_LogIngest_ObjectId }
|
|        # #475 -- A TABLE + RULE ALREADY MADE READY IN THIS PROCESS FOR THESE COLUMNS IS NOT CHECKED AGAIN. The steps below
|        # (endpoint + rule selection twice, the table / rule update with its coverage check, the cache refresh) are several
|        # Azure calls; they ran for every batch, and a run collected in parts posts its records in dozens of batches
|        # (customer H 2026-10-09: 96,551 records). A batch whose columns were all made ready earlier in this process posts
|        # through the same pinned endpoint and rule; a batch with a NEW column takes the full path again.
|        $readyKey = ('{0}|{1}' -f $TableName, $DcrName).ToLowerInvariant()
|        $batchCols = Get-SIObjectMapColumns -Rows @($Rows)
|        # in the run cache (global, like the tokens: this file is dot-sourced at different depths, so $script: differs)
|        $rcache = Get-SILogIngestRunCache
|        if (-not ($rcache.ObjectMapReady -is [hashtable])) { $rcache.ObjectMapReady = @{} }
|        $ready = $rcache.ObjectMapReady[$readyKey]
|        if ($ready -and (Test-SIObjectMapColumnsReady -Ready $ready.Columns -Columns $batchCols)) {
|            $global:AzDceDetails = @($ready.Dce); $global:AzDcrDetails = @($ready.Dcr)
|            $data = @($Rows)
|            $data = Repair-SILogColumnName -Data $data 4>$null
|            $data = Format-SILogRowsToSchema -Data $data 4>$null
|            $null = Send-SILogData -DceName $global:SI_DceName -DcrName $DcrName -Data $data -TableName $TableName @authParams 4>$null
|            return @($data).Count
|        }
|        # several processes of one run publish at once (the records of a run collected in parts): the table / rule update
|        # is done by one at a time (SI_INGEST_LOCK_FILE), so two never update the same rule over each other
|        $lock = Enter-SIIngestLock
|
|        # 🔴 THE WHOLE SET, NOT ONE ROW -- CORRECTED 2026-08-31. `-Data` was
|        # `@($Rows | Select-Object -First 1)`. AzLogDcrIngestPS INFERS the table + DCR column set
|        # from what it is handed, so one row defined the schema for the entire table: a row lacking
|        # an optional field meant that column was never created, and every other row's value for it
|        # was DROPPED AT INGEST, silently, for the life of the table.
|        # 🪤 Nothing errors. The engine reports rows posted, the table exists, and the field is
|        # simply absent -- indistinguishable from "no object had a value".
|        # 📌 The four profilers already got this right (Invoke-Output.ps1's `$schemaSample` is the
|        # FULL dataset, commented "full dataset for type inference"). Only the engines that publish
|        # their own v3 tables carried the shortcut.
|        #
|        # 🔴 AND THIS COMMENT MUST STAY *ABOVE* THE CALL, NOT INSIDE IT (audit #102, 2026-09-02).
|        # It was written between two backtick-continued argument lines, and **a comment TERMINATES a
|        # backtick continuation**: everything after it was dropped, including the `-Data @($Rows)` this
|        # very comment was added to introduce. Correlation then failed at publish on every run --
|        # `missing mandatory parameters: Data AzDcrSetLogIngestApiAppPermissionsDcrLevel
|        # AzLogDcrTableCreateFromReferenceMachine`, which is exactly the arguments that follow it here.
|        # #199 -- pin BEFORE the create/update, not only before the post.
|        Select-SIIngestTarget -AuthParams $authParams -DcrName $DcrName
|        $null = Update-SILogTableSchema `
|            -AzLogWorkspaceResourceId                   $global:SI_WorkspaceResourceId `
|            @authParams `
|            -DceName                                    $global:SI_DceName `
|            -DcrName                                    $DcrName `
|            -DcrResourceGroup                           $global:SI_DcrResourceGroup `
|            -TableName                                  $TableName `
|            -Data                                       @($Rows) `
|            -LogIngestServicePricipleObjectId           $spnObjectId `
|            -AzDcrSetLogIngestApiAppPermissionsDcrLevel $false `
|            -AzLogDcrTableCreateFromAnyMachine          $true `
|            -AzLogDcrTableCreateFromReferenceMachine    @() 4>$null
|
|        # Re-sync the DCE/DCR cache so a freshly created DCR's immutableId is known before the
|        # name-only lookup inside Post-*. Without it the module falls back to the DCE's location
|        # field as a bogus immutableId and the ingestion API answers 404 'westeurope'.
|        try {
|            $ensureFn = Get-Command -Name 'Ensure-SecurityInsightAzDceDcrCache' -ErrorAction Ignore
|            if ($ensureFn) {
|                & $ensureFn @authParams `
|                    -SubscriptionId   $global:SI_AzSubscriptionId `
|                    -DceResourceGroup $global:SI_DceResourceGroup `
|                    -DcrResourceGroup $global:SI_DcrResourceGroup `
|                    -Force 4>$null
|            }
|        } catch { }
|
|        # 📌 SUPERSEDED 2026-10-01 (#199): Select-SIIngestTarget above now builds and pins the caches BEFORE the
|        # create/update -- the module resolves the endpoint by name inside CheckCreateUpdate too, so pinning only
|        # here was too late. The history below is kept for the BlockCopy lesson.
|        # 🪤 DO NOT PRE-POPULATE THE CACHES HERE. Tried on 2026-08-30, mirroring the profiler's
|        # `$global:AzDceDetails = Get-AzDceListAll @authParams`, on the reasoning that filtering a
|        # cache that does not exist yet would be a silent no-op. It is not a no-op -- by this point
|        # `CheckCreateUpdate-TableDcr-Structure` (called above) has already built both caches, which
|        # is why the DCR pin below has always worked. The rebuild is redundant work, nothing more.
|        # 📌 It was briefly believed to have CAUSED the "BlockCopy ... Object must be an array of
|        # primitives" error that appeared once the 403 was gone. It did not, and the wrong version of
|        # this note lived here for an hour. That error was a real defect in AzLogDcrIngestPS 1.7.1 --
|        # `return $bytes` enumerates the array, so the caller binds object[] and [Buffer]::BlockCopy
|        # rejects it -- which broke the UNCOMPRESSED path for every caller of the module. Fixed
|        # upstream in 1.7.2 (SI finding #81). Removing these lines did not make it go away; only the
|        # module fix did.
|
|        # DCR name-collision guard. One SPN can see same-named DCRs in several subscriptions -- there
|        # are already three DCEs called dce-securityinsight in this tenant -- and the module's name-only
|        # lookup then picks one at random. Pin to (sub + RG + name) before posting.
|        if ($global:AzDcrDetails -and $global:SI_AzSubscriptionId -and $global:SI_DcrResourceGroup) {
|            $picked = @($global:AzDcrDetails | Where-Object {
|                $_.name -eq $DcrName -and
|                $_.id   -like "*/subscriptions/$($global:SI_AzSubscriptionId)/resourceGroups/$($global:SI_DcrResourceGroup)/*"
|            }) | Select-Object -First 1
|            if ($picked) { $global:AzDcrDetails = @($picked) }
|        }
|
|        # 🔴 AND THE SAME GUARD FOR THE **DCE** -- its absence is why this engine could never publish.
|        # The comment above names the hazard exactly ("three DCEs called dce-securityinsight") and then
|        # pins only the DCR. `Post-*` resolves the DCE by NAME-ONLY against $global:AzDceDetails, so it
|        # could pick an endpoint in a DIFFERENT subscription and post this workspace's DCR immutableId
|        # to it -- which the Log Ingestion API answers with **HTTP 403**.
|        # MEASURED 2026-08-30: three DCEs named `dce-securityinsight` exist across this tenant (one in
|        # the workspace's own subscription, two in a sibling), and every correlation run ended
|        # `[ERROR] Engine failed: Log Ingestion API request failed. HTTP Status: 403` AFTER doing all
|        # of its real work -- 1296 rows read, 1291 objects correlated, ledger updated, 2228 map rows
|        # built -- and losing the lot at the final POST. That is why the handoff records correlation as
|        # "built + run on real data, never published": it was never a correlation defect at all.
|        # 🔑 THE PROFILER ALREADY SOLVES THIS. `Apply-SIDcrScopeFilter` (asset-profiling/stages/
|        # Invoke-Output.ps1) filters BOTH caches to the configured sub + RG, which is exactly why the
|        # four profilers ingest happily while this engine 403s on the same credentials. Operator,
|        # 2026-08-30: *"it must use same auth as the design is using to send data to la in the
|        # profiler"* -- so this mirrors that filter rather than inventing a third variant.
|        # 📌 Same auth params, same scope pin. The DCE RG falls back to the DCR RG, matching the
|        # profiler's own default of 'rg-securityinsight' when SI_DceResourceGroup is unset.
|        $_dceRg = if ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup }
|                  else { [string]$global:SI_DcrResourceGroup }
|        if ($global:AzDceDetails -and $global:SI_AzSubscriptionId -and $_dceRg) {
|            $_pickedDce = @($global:AzDceDetails | Where-Object {
|                $_.id -like "*/subscriptions/$($global:SI_AzSubscriptionId)/resourceGroups/$_dceRg/*"
|            })
|            if ($_pickedDce.Count -gt 0) { $global:AzDceDetails = @($_pickedDce) }
|        }
|
|        # #199 -- again before the post: the cache refresh above narrowed it to this install's endpoint, which is
|        # not the rule's own when the rule is bound elsewhere.
|        Select-SIIngestTarget -AuthParams $authParams -DcrName $DcrName
|        # ready for these columns in this process (#475): the next batch with no new column posts straight away
|        $known = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|        if ($ready) { foreach ($c in $ready.Columns) { [void]$known.Add($c) } }
|        foreach ($c in $batchCols) { [void]$known.Add($c) }
|        $rcache.ObjectMapReady[$readyKey] = [pscustomobject]@{ Columns = $known; Dce = @($global:AzDceDetails); Dcr = @($global:AzDcrDetails) }
|        Exit-SIIngestLock -Lock $lock; $lock = $null
|        $data = @($Rows)
|        $data = Repair-SILogColumnName -Data $data 4>$null
|        $data = Format-SILogRowsToSchema -Data $data 4>$null
|        $null = Send-SILogData `
|            -DceName   $global:SI_DceName `
|            -DcrName   $DcrName `
|            -Data      $data `
|            -TableName $TableName `
|            @authParams 4>$null
|
|        @($data).Count
|    }
|    finally {
|        if ($lock) { Exit-SIIngestLock -Lock $lock }
|        if ($null -ne $savedVerbose) { $global:VerbosePreference = $savedVerbose }
|    }
|}
|
|function Get-SIObjectMapColumns {
|    <# PURE. Every column name of a batch of rows (PSObject properties or dictionary keys), once. #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    $set = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($r in $Rows) {
|        if ($null -eq $r) { continue }
|        if ($r -is [System.Collections.IDictionary]) { foreach ($k in $r.Keys) { [void]$set.Add([string]$k) } }
|        else { foreach ($p in $r.PSObject.Properties) { [void]$set.Add($p.Name) } }
|    }
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($c in $set) { $out.Add($c) }
|    , $out.ToArray()
|}
|
|function Test-SIObjectMapColumnsReady {
|    <# PURE. $true when every column of the batch is among the columns already made ready. #>
|    param($Ready, [AllowEmptyCollection()][string[]]$Columns = @())
|    if ($null -eq $Ready) { return $false }
|    foreach ($c in $Columns) { if (-not $Ready.Contains($c)) { return $false } }
|    $true
|}
|
|function Enter-SIIngestLock {
|    <#
|        The cross-process lock of the table / rule update (SI_INGEST_LOCK_FILE, set by a parent that runs several publishing
|        processes at once). No variable = no lock ($null). Waits up to 20 minutes; then goes on without it, said once -- a
|        lock that cannot be taken never stops a publish (the coverage check before every post still guards the rule).
|    #>
|    param([int]$WaitSeconds = 1200)
|    $path = [string][Environment]::GetEnvironmentVariable('SI_INGEST_LOCK_FILE')
|    if ([string]::IsNullOrWhiteSpace($path)) { return $null }
|    $until = [datetime]::UtcNow.AddSeconds($WaitSeconds)
|    while ([datetime]::UtcNow -lt $until) {
|        try { return [System.IO.File]::Open($path, [System.IO.FileMode]::OpenOrCreate, [System.IO.FileAccess]::ReadWrite, [System.IO.FileShare]::None) }
|        catch { Start-Sleep -Milliseconds 500 }
|    }
|    Write-Warning ('the table update lock ({0}) was not free for {1} seconds -- this process goes on without it' -f $path, $WaitSeconds)
|    $null
|}
|
|function Exit-SIIngestLock {
|    param($Lock)
|    if ($Lock) { try { $Lock.Dispose() } catch { } }
|}
|
|# =====================================================================================================================
|#  LOG INGESTION OVER PLAIN REST -- SecurityInsight needs no PowerShell module (no AzLogDcrIngestPS, no Az.*).
|# =====================================================================================================================
|<#
|    Every SI call site calls the SI wrapper of the job; each wrapper does it over plain REST (its *Rest function):
|
|        SI wrapper                  replaces (AzLogDcrIngestPS)                            SI REST function
|        Get-SIDceList               Get-AzDceListAll                                       Get-SIDceListRest
|        Get-SIDcrList               Get-AzDcrListAll                                       Get-SIDcrListRest
|        Update-SILogTableSchema     CheckCreateUpdate-TableDcr-Structure                   Update-SILogTableSchemaRest
|        Send-SILogData              Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output     Send-SILogDataRest
|        Add-SICollectionTime        Add-CollectionTimeToAllEntriesInArray                  Add-SICollectionTimeRest
|        Add-SIColumnData            Add-ColumnDataToAllEntriesInArray                      Add-SIColumnDataRest
|        Repair-SILogColumnName      ValidateFix-AzLogAnalyticsTableSchemaColumnNames       Repair-SILogColumnNameRest
|        Format-SILogRowsToSchema    Build-DataArrayToAlignWithSchema                       Format-SILogRowsToSchemaRest
|        Get-SILogSchemaArray        Get-ObjectSchemaAsArray                                Get-SILogSchemaRest -As Array
|        Get-SILogSchemaHash         Get-ObjectSchemaAsHash                                 Get-SILogSchemaRest -As Hash
|        Test-SILogTableDcrStatus    Get-AzLogAnalyticsTableAzDataCollectionRuleStatus      Test-SILogTableDcrStatusRest
|        Set-SILogTable              CreateUpdate-AzLogAnalyticsCustomLogTableDcr           Set-SILogTableRest
|        Set-SILogDcr                CreateUpdate-AzDataCollectionRuleLogIngestCustomLog    Set-SILogDcrRest
|
|    The wrappers keep the parameter names and types the call sites were written against, so no call site changed.
|
|    PS 5.1 safe: no ?. / ??, no RSA.ImportFromPem. Works on pwsh 7 / Linux (no Cert: drive needed). Community + Pro:
|    this file never references a Pro path.
|#>
|
|function Get-SILogIngestWrapperMap {
|    <# The wrapper -> replaced function -> REST function table above, as data (the wiring tests read it). #>
|    [ordered]@{
|        'Get-SIDceList'            = @{ Replaces = 'Get-AzDceListAll';                                   Rest = 'Get-SIDceListRest' }
|        'Get-SIDcrList'            = @{ Replaces = 'Get-AzDcrListAll';                                   Rest = 'Get-SIDcrListRest' }
|        'Update-SILogTableSchema'  = @{ Replaces = 'CheckCreateUpdate-TableDcr-Structure';               Rest = 'Update-SILogTableSchemaRest' }
|        'Send-SILogData'           = @{ Replaces = 'Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output'; Rest = 'Send-SILogDataRest' }
|        'Add-SICollectionTime'     = @{ Replaces = 'Add-CollectionTimeToAllEntriesInArray';              Rest = 'Add-SICollectionTimeRest' }
|        'Add-SIColumnData'         = @{ Replaces = 'Add-ColumnDataToAllEntriesInArray';                  Rest = 'Add-SIColumnDataRest' }
|        'Repair-SILogColumnName'   = @{ Replaces = 'ValidateFix-AzLogAnalyticsTableSchemaColumnNames';   Rest = 'Repair-SILogColumnNameRest' }
|        'Format-SILogRowsToSchema' = @{ Replaces = 'Build-DataArrayToAlignWithSchema';                   Rest = 'Format-SILogRowsToSchemaRest' }
|        'Get-SILogSchemaArray'     = @{ Replaces = 'Get-ObjectSchemaAsArray';                            Rest = 'Get-SILogSchemaRest' }
|        'Get-SILogSchemaHash'      = @{ Replaces = 'Get-ObjectSchemaAsHash';                             Rest = 'Get-SILogSchemaRest' }
|        'Test-SILogTableDcrStatus' = @{ Replaces = 'Get-AzLogAnalyticsTableAzDataCollectionRuleStatus';  Rest = 'Test-SILogTableDcrStatusRest' }
|        'Set-SILogTable'           = @{ Replaces = 'CreateUpdate-AzLogAnalyticsCustomLogTableDcr';       Rest = 'Set-SILogTableRest' }
|        'Set-SILogDcr'             = @{ Replaces = 'CreateUpdate-AzDataCollectionRuleLogIngestCustomLog'; Rest = 'Set-SILogDcrRest' }
|    }
|}
|
|# ---- the wrappers ------------------------------------------------------------------------------------------------
|# Each declares the parameters the call sites pass (names + types) and forwards @PSBoundParameters: only what the call
|# site bound, with the value it bound, including -Verbose:$false. NOT `@args`: measured 2026-10-03 on PS 5.1 and 7.6,
|# `@args` splits `-Name:$value` into a bare switch plus a positional value.
|
|function Get-SIDceList {
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Get-SIDceListRest @PSBoundParameters)
|}
|
|function Get-SIDcrList {
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Get-SIDcrListRest @PSBoundParameters)
|}
|
|function Get-SIDcrCreateRefusal {
|    <# PURE. The line of a DCR / table create's captured output in which Azure (or the create itself) REFUSED it -- the
|       Microsoft answer to surface, '' when there is none. A refused create never makes the rule appear, so it is not waited for.
|       'skipping create' / 'already exists in' (a rule of that name in ANOTHER resource group) is a refusal too: the create did nothing. #>
|    param([AllowNull()][AllowEmptyString()][string]$CreateOutput)
|    if ([string]::IsNullOrWhiteSpace($CreateOutput)) { return '' }
|    $re = '(?i)AuthorizationFailed|LinkedAuthorizationFailed|\(Forbidden\)|\b403\b|\(Unauthorized\)|\b401\b|InvalidPayload|InvalidTemplate|InvalidRequestContent|BadRequest|ResourceGroupNotFound|SubscriptionNotFound|WorkspaceNotFound|Step 3 threw|skipping create|already exists in'
|    foreach ($l in ($CreateOutput -split '\r?\n')) { if ($l -match $re) { return $l.Trim() } }
|    ''
|}
|
|function Wait-SIDcrReady {
|    <#
|        Fix request 2a40d950 (owner 2026-10-22: no fixed limits on SI's own work): after the table / rule create, WAIT UNTIL
|        THE RULE IS READY and read it back -- never a fixed number of seconds that gives up while Azure is still making it
|        (it was 240 s). A not-found / no-immutableId answer right after a create means "not yet" (REQUIREMENTS #619). It stops
|        only on EVIDENCE that waiting cannot help, and says Microsoft's answer:
|          * the create's own output carries a refusal (Get-SIDcrCreateRefusal) -- before any wait;
|          * Azure says the rule's provisioning FAILED;
|          * reading the rule is refused (401 / 403 -- the identity may not read it);
|          * the create has RETURNED and two read-backs in a row, spaced by the progress pace (-MaxPauseSeconds), find NO rule
|            at all: the create did nothing, so waiting cannot help (review S1: it polled until the job died). A rule that IS
|            there but still provisioning is waited for without a deadline.
|        Any other failed read is a transient answer: said, and read again. Progress is said on every read (elapsed, what was
|        seen); the first read is at once (a rule that is already there costs no wait); the pause between reads grows from -FirstPauseSeconds to -MaxPauseSeconds (a pace, never a deadline).
|        -Probe { } -> @{ ImmutableId; State } of the rule as SI's own lists see it now ($null = not there yet); it throws
|        when the read fails. -Sleep { param($s) } / -Log { param($m) } are seams. Returns @{ Ready; ImmutableId; Waited; Why }.
|    #>
|    param([Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][scriptblock]$Probe, [AllowNull()][AllowEmptyString()][string]$CreateOutput,
|          [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s }, [scriptblock]$Log = { param($m) Write-Host $m },
|          [int]$FirstPauseSeconds = 15, [int]$MaxPauseSeconds = 60, [AllowEmptyString()][string]$Location = '')
|    $refused = Get-SIDcrCreateRefusal -CreateOutput $CreateOutput
|    if ($refused) {
|        # read back ONCE: a refusal of a later part (the table, a role) can come after the rule itself was made -- then it is used
|        $r = $null; try { $r = & $Probe } catch { $r = $null }
|        if ($null -ne $r -and [string]$r.ImmutableId -and [string]$r.ImmutableId -notlike '*location*' -and [string]$r.ImmutableId -ne $Location -and [string]$r.State -notmatch '(?i)^failed$') {
|            & $Log ("DCR '{0}' is ready although the create reported: {1}" -f $DcrName, $refused)
|            return @{ Ready = $true; ImmutableId = [string]$r.ImmutableId; Waited = 0; Why = '' }
|        }
|        return @{ Ready = $false; ImmutableId = ''; Waited = 0; Why = ("the create of DCR '{0}' was refused -- {1}" -f $DcrName, $refused) }
|    }
|    $waited = 0; $pause = [Math]::Max(1, $FirstPauseSeconds); $absent = 0
|    while ($true) {
|        $seen = 'not there yet'
|        try {
|            $r = & $Probe
|            if ($null -ne $r) {
|                $imm = [string]$r.ImmutableId; $st = [string]$r.State
|                if ($st -match '(?i)^failed$') { return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("Azure reports DCR '{0}' with provisioning state Failed" -f $DcrName) } }
|                if ($imm -and $imm -notlike '*location*' -and $imm -ne $Location) { & $Log ("DCR immutableId resolved after {0}s: {1}" -f $waited, $imm); return @{ Ready = $true; ImmutableId = $imm; Waited = $waited; Why = '' } }
|                $seen = $(if ($st) { "there, provisioning state $st, no immutableId yet" } else { 'there, no immutableId yet' })
|                $absent = 0
|            } else {
|                $absent++
|                if ($absent -ge 2) {
|                    $said = @(([string]$CreateOutput) -split '\r?\n' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
|                    $answer = $(if ($said.Count) { $said[-1] } else { 'nothing (the create returned no output)' })
|                    return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("the rule was not created; Azure answered: {0} -- DCR '{1}' was not found on two read-backs {2}s apart after the create returned" -f $answer, $DcrName, [Math]::Max(1, $MaxPauseSeconds)) }
|                }
|            }
|        } catch {
|            $m = ("$($_.Exception.Message)" -replace '\s+', ' ').Trim()
|            if ($m -match '(?i)\b401\b|\b403\b|AuthorizationFailed|Forbidden|Unauthorized') { return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("reading DCR '{0}' was refused -- {1}" -f $DcrName, $m) } }
|            $seen = "the read failed ($m) -- read again"
|        }
|        & $Log ("waiting for DCR '{0}' to be ready ({1}s so far; {2}) ..." -f $DcrName, $waited, $seen)
|        # after a read that found no rule at all, the next read is a full progress pace later (the second read-back of the stop rule)
|        $nap = $(if ($absent -ge 1) { [Math]::Max($pause, [Math]::Max(1, $MaxPauseSeconds)) } else { $pause })
|        & $Sleep $nap
|        $waited += $nap
|        $pause = [Math]::Min([Math]::Max(1, $MaxPauseSeconds), $pause * 2)
|    }
|}
|
|function Update-SILogTableSchema {
|    [CmdletBinding()]
|    param([Array]$Data, [string]$AzLogWorkspaceResourceId, [string]$TableName, [string]$DcrName, [string]$DcrResourceGroup, [string]$DceName,
|          [AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel,
|          [boolean]$AzLogDcrTableCreateFromAnyMachine, [string]$SchemaMode, [boolean]$EnableUploadViaLogHub,
|          [AllowEmptyCollection()][array]$AzLogDcrTableCreateFromReferenceMachine,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    # A rule that already feeds ANOTHER table is never repurposed, and columns this call adds to an existing rule are
|    # noted so the post can check that they are stored (Start-SILogDcrWatch / Complete-SILogDcrWatch, below).
|    $watch = Start-SILogDcrWatch -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -Bound $PSBoundParameters
|    # A NEW rule for a table that already exists is declared from the TABLE (its columns, with their types):
|    # Set-SILogDcrRest does this itself.
|    $out = Update-SILogTableSchemaRest @PSBoundParameters
|    # The rule this install posts through must declare EVERY column of the data -- a column it does not declare is
|    # dropped by Azure without an error. Missing ones are added from the table; any still missing refuses the post.
|    # Before Complete-SILogDcrWatch, so columns added here are checked after the post like any other new column.
|    $null = Assert-SILogDcrCoversData -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -DceName $DceName -Data $Data -Bound $PSBoundParameters
|    Complete-SILogDcrWatch -Watch $watch
|    $out
|}
|
|function Send-SILogData {
|    [CmdletBinding()]
|    param([array]$Data, [AllowEmptyString()][string]$DcrName, [AllowEmptyString()][string]$DceName, [string]$TableName,
|          [string]$BatchAmount, [bool]$EnableUploadViaLogHub, [string]$LogHubPath,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation, [string]$TenantId,
|          [Nullable[bool]]$EnableCompression, [Nullable[bool]]$UseManagedIdentity, [string]$ManagedIdentityClientId)
|    $out = Send-SILogDataRest @PSBoundParameters
|    # Columns added to this rule earlier in the run: check that Log Analytics really stores their values.
|    Confirm-SILogNewColumns -DcrName $DcrName -TableName $TableName -Data $Data -Bound $PSBoundParameters
|    $out
|}
|
|function Add-SICollectionTime {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Add-SICollectionTimeRest @PSBoundParameters)
|}
|
|function Add-SIColumnData {
|    [CmdletBinding()]
|    param([Array]$Data, [string]$Column1Name, [string]$Column1Data, [string]$Column2Name, [string]$Column2Data, [string]$Column3Name, [string]$Column3Data)
|    return (Add-SIColumnDataRest @PSBoundParameters)
|}
|
|function Repair-SILogColumnName {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Repair-SILogColumnNameRest @PSBoundParameters)
|}
|
|function Format-SILogRowsToSchema {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Format-SILogRowsToSchemaRest @PSBoundParameters)
|}
|
|function Get-SILogSchemaArray {
|    [CmdletBinding()]
|    param([Array]$Data, [string[]]$ReturnType)
|    return (Get-SILogSchemaRest -As Array @PSBoundParameters)
|}
|
|function Get-SILogSchemaHash {
|    [CmdletBinding()]
|    param([Array]$Data, [string[]]$ReturnType)
|    return (Get-SILogSchemaRest -As Hash @PSBoundParameters)
|}
|
|function Test-SILogTableDcrStatus {
|    [CmdletBinding()]
|    param([string]$AzLogWorkspaceResourceId, [string]$TableName, [string]$DcrName, [array]$SchemaSourceObject,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Test-SILogTableDcrStatusRest @PSBoundParameters)
|}
|
|function Set-SILogTable {
|    [CmdletBinding()]
|    param([string]$TableName, [array]$SchemaSourceObject, [string]$AzLogWorkspaceResourceId, [string]$SchemaMode,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Set-SILogTableRest @PSBoundParameters)
|}
|
|function Set-SILogDcr {
|    [CmdletBinding()]
|    param([array]$SchemaSourceObject, [string]$AzLogWorkspaceResourceId, [string]$DceName, [string]$DcrResourceGroup, [string]$DcrName, [string]$TableName,
|          [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel, [AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [string]$SchemaMode,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $watch = Start-SILogDcrWatch -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -Bound $PSBoundParameters
|    $out = Set-SILogDcrRest @PSBoundParameters
|    Complete-SILogDcrWatch -Watch $watch
|    $out
|}
|
|# =====================================================================================================================
|#  A RULE IS NEVER REPURPOSED, AND NEW COLUMNS ARE CHECKED -- both engines (these run around the wrappers above)
|#
|#  1. A data collection rule that already feeds ANOTHER table is never changed to feed this one. Measured in the 2.2 ->
|#     3.0 upgrade test: a setup-written 2.2 config named its public-IP rule 'dcr-si-publicip-profile' (feeding the 2.2
|#     public-IP table); 3.0's own default uses the same name for its new table, and the module REWROTE the rule -- the
|#     old flow was gone and the first post failed. Start-SILogDcrWatch refuses before anything is written.
|#  2. Columns added to an EXISTING rule land empty for a while: Azure accepts the post, but drops the new columns'
|#     values until the change has reached the ingestion pipeline (measured: the first 3.0 run after the upgrade wrote
|#     SI_AssetName / SI_AssetId empty on 134 of 134 rows; empty again 4 and 18 minutes after a column was added; filled
|#     hours later). The rule shows the new column at once, so the rule itself is no signal. Complete-SILogDcrWatch
|#     notes what was added; Confirm-SILogNewColumns, after the post, asks Log Analytics whether this run's values were
|#     STORED, and when they were not, the run says so and records it (Get-SILogIngestNotes -> the run's outcome is
|#     success-partial, so nothing downstream reads the snapshot as whole).
|#  Every read here is best effort: a rule that cannot be read is never a reason to stop a publish -- only a rule that IS
|#  read and feeds another table is.
|# =====================================================================================================================
|
|function Get-SILogDcrStreams {
|    <# PURE. The streams an existing rule writes: each data flow's outputStream, else the flow's streams; a rule with
|       no data flows -> its declared streams. #>
|    param([AllowNull()]$Dcr)
|    $out = New-Object System.Collections.Generic.List[string]
|    if ($null -eq $Dcr -or $null -eq $Dcr.properties) { return @() }
|    foreach ($f in @($Dcr.properties.dataFlows)) {
|        if ($null -eq $f) { continue }
|        $names = if ($f.PSObject.Properties['outputStream'] -and $f.outputStream) { @([string]$f.outputStream) } else { @(@($f.streams) | ForEach-Object { [string]$_ }) }
|        foreach ($n in $names) { if ($n -and -not $out.Contains($n)) { [void]$out.Add($n) } }
|    }
|    if ($out.Count -eq 0 -and $Dcr.properties.streamDeclarations) {
|        foreach ($p in $Dcr.properties.streamDeclarations.PSObject.Properties) { [void]$out.Add([string]$p.Name) }
|    }
|    return $out.ToArray()
|}
|
|function Test-SILogDcrFeedsOtherTable {
|    <# PURE. $true when the rule exists, writes at least one stream, and none of its streams is this table's. #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName)
|    $streams = @(Get-SILogDcrStreams -Dcr $Dcr)
|    if ($streams.Count -eq 0) { return $false }
|    $t = $TableName -replace '_CL$', ''
|    $mine = @(('Custom-' + $t + '_CL'), (Get-SILogStreamName -TableName $t))
|    foreach ($s in $streams) { if ($mine -contains $s) { return $false } }
|    return $true
|}
|
|function Get-SILogDcrStreamColumns {
|    <# PURE. The column names the rule declares for this table's stream (empty when it declares none). #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName)
|    if ($null -eq $Dcr -or $null -eq $Dcr.properties -or -not $Dcr.properties.streamDeclarations) { return @() }
|    $t = $TableName -replace '_CL$', ''
|    foreach ($s in @(('Custom-' + $t + '_CL'), (Get-SILogStreamName -TableName $t))) {
|        $p = $Dcr.properties.streamDeclarations.PSObject.Properties[$s]
|        if ($p) { return @(@($p.Value.columns) | Where-Object { $_ } | ForEach-Object { [string]$_.name }) }
|    }
|    return @()
|}
|
|function Get-SILogAddedColumns {
|    <# PURE. Columns in -After that -Before did not have. #>
|    param([AllowEmptyCollection()][string[]]$Before = @(), [AllowEmptyCollection()][string[]]$After = @())
|    return @(@($After) | Where-Object { $_ -and (@($Before) -notcontains $_) })
|}
|
|function Get-SILogAlternateDcrName {
|    <# PURE. A distinct, deterministic rule name for this install: '<name>-<resource group>', or '<name>-<8-character
|       hash of the resource group>' when that would pass 60 characters -- the rule the profilers' collision rename
|       already uses, so every run derives the same name. #>
|    param([Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][string]$ResourceGroup)
|    $rgClean = ($ResourceGroup -replace '[^a-zA-Z0-9-]', '-').ToLowerInvariant().Trim('-')
|    $name = "$DcrName-$rgClean"
|    if ($name.Length -gt 60) {
|        $sha = [System.Security.Cryptography.SHA1]::Create()
|        try { $h = $sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ResourceGroup.ToLowerInvariant())) } finally { $sha.Dispose() }
|        $name = "$DcrName-" + (([BitConverter]::ToString($h) -replace '-', '').Substring(0, 8).ToLowerInvariant())
|    }
|    return $name
|}
|
|function Get-SILogDcrRepurposeMessage {
|    <# The one sentence a refused rule produces. #>
|    param([string]$DcrName, [string]$ResourceGroup, [string[]]$Streams, [string]$TableName)
|    $feeds = (@($Streams) | ForEach-Object { $_ -replace '^Custom-', '' }) -join ', '
|    ("The data collection rule '{0}' (resource group '{1}') already sends data to {2}. It is left unchanged -- changing it to send {3}_CL would stop the data it carries now. Give {3}_CL a rule of its own: set this table's data collection rule name in config\SecurityInsight.custom.ps1 to a new name (it is created automatically)." -f `
|        $DcrName, $ResourceGroup, $feeds, ($TableName -replace '_CL$', ''))
|}
|
|function Get-SILogDcrState {
|    <#
|        The rule as Azure has it NOW (never from the run cache): Known = $false when it cannot be read (no subscription /
|        resource group configured, or the read failed); else Dcr = the rule, or $null when it does not exist.
|    #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$WorkspaceResourceId, $Bound)
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $WorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    if (-not $DcrName -or -not $scope.Subscription -or -not $scope.DcrRg) { return [pscustomobject]@{ Known = $false; Dcr = $null; ResourceGroup = $scope.DcrRg } }
|    try {
|        $auth = Resolve-SILogIngestAuth -Bound $Bound
|        $d = Invoke-SILogArm -Path "/subscriptions/$($scope.Subscription)/resourceGroups/$($scope.DcrRg)/providers/Microsoft.Insights/dataCollectionRules/$DcrName" `
|                 -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -AllowNotFound -NoCache
|        return [pscustomobject]@{ Known = $true; Dcr = $d; ResourceGroup = $scope.DcrRg }
|    } catch {
|        Write-Verbose ("data collection rule '{0}' could not be read before the update: {1}" -f $DcrName, $_.Exception.Message)
|        return [pscustomobject]@{ Known = $false; Dcr = $null; ResourceGroup = $scope.DcrRg }
|    }
|}
|
|function Resolve-SILogDcrNameForTable {
|    <#
|        The rule name this table should post through: -DcrName, unless that rule exists and feeds ANOTHER table -- then
|        Get-SILogAlternateDcrName (when that one is free or already this table's). When the alternate is taken too, the
|        original name is returned and the wrapper refuses it with a clear message. Unknown (cannot be read) -> unchanged.
|        Returns Name + Reason (empty when unchanged).
|    #>
|    param([Parameter(Mandatory)][string]$DcrName, [string]$DcrResourceGroup, [Parameter(Mandatory)][string]$TableName, [string]$WorkspaceResourceId, $Bound)
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $Bound
|    if (-not $st.Known -or -not $st.Dcr -or -not (Test-SILogDcrFeedsOtherTable -Dcr $st.Dcr -TableName $TableName)) {
|        return [pscustomobject]@{ Name = $DcrName; Reason = '' }
|    }
|    $alt = Get-SILogAlternateDcrName -DcrName $DcrName -ResourceGroup ([string]$st.ResourceGroup)
|    $st2 = Get-SILogDcrState -DcrName $alt -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $Bound
|    if ($st2.Known -and $st2.Dcr -and (Test-SILogDcrFeedsOtherTable -Dcr $st2.Dcr -TableName $TableName)) {
|        return [pscustomobject]@{ Name = $DcrName; Reason = '' }
|    }
|    $feeds = (@(Get-SILogDcrStreams -Dcr $st.Dcr) | ForEach-Object { $_ -replace '^Custom-', '' }) -join ', '
|    [pscustomobject]@{
|        Name   = $alt
|        Reason = ("the data collection rule '{0}' already sends data to {1} and is left unchanged; {2}_CL uses its own rule '{3}'." -f $DcrName, $feeds, ($TableName -replace '_CL$', ''), $alt)
|    }
|}
|
|function Start-SILogDcrWatch {
|    <# Before a rule is created / updated: refuse a rule that feeds another table; remember the columns it declares. #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$TableName, [string]$WorkspaceResourceId, $Bound)
|    if (-not $DcrName -or -not $TableName) { return $null }
|    $b = @{}; if ($Bound) { foreach ($k in @($Bound.Keys)) { if ($k -notin 'Data', 'SchemaSourceObject') { $b[$k] = $Bound[$k] } } }
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|    if (-not $st.Known) { return $null }
|    if ($st.Dcr -and (Test-SILogDcrFeedsOtherTable -Dcr $st.Dcr -TableName $TableName)) {
|        throw (Get-SILogDcrRepurposeMessage -DcrName $DcrName -ResourceGroup ([string]$st.ResourceGroup) -Streams @(Get-SILogDcrStreams -Dcr $st.Dcr) -TableName $TableName)
|    }
|    [pscustomobject]@{
|        DcrName = $DcrName; DcrResourceGroup = $DcrResourceGroup; TableName = ($TableName -replace '_CL$', ''); WorkspaceResourceId = $WorkspaceResourceId
|        Bound = $b; Existed = [bool]$st.Dcr; Before = @(Get-SILogDcrStreamColumns -Dcr $st.Dcr -TableName $TableName)
|    }
|}
|
|function Complete-SILogDcrWatch {
|    <# After the update: columns an EXISTING rule gained are noted for Confirm-SILogNewColumns. Never throws. #>
|    param($Watch)
|    if (-not $Watch -or -not $Watch.Existed) { return }
|    # The run-health record does not check itself: it is the record a check would report into.
|    if ($Watch.TableName -ieq 'SI_RunHealth') { return }
|    try {
|        $st = Get-SILogDcrState -DcrName $Watch.DcrName -DcrResourceGroup $Watch.DcrResourceGroup -WorkspaceResourceId $Watch.WorkspaceResourceId -Bound $Watch.Bound
|        if (-not $st.Known -or -not $st.Dcr) { return }
|        $added = @(Get-SILogAddedColumns -Before $Watch.Before -After @(Get-SILogDcrStreamColumns -Dcr $st.Dcr -TableName $Watch.TableName))
|        if ($added.Count -eq 0) { return }
|        if (-not ($global:SI_LogIngestNewColumns -is [hashtable])) { $global:SI_LogIngestNewColumns = @{} }
|        $key = $Watch.DcrName.ToLowerInvariant()
|        $ws = if ($Watch.WorkspaceResourceId) { $Watch.WorkspaceResourceId } else { [string]$global:SI_WorkspaceResourceId }
|        if ($global:SI_LogIngestNewColumns.ContainsKey($key)) {
|            $prev = $global:SI_LogIngestNewColumns[$key]
|            $added = @(@($prev.Columns) + @($added) | Select-Object -Unique)
|        }
|        $global:SI_LogIngestNewColumns[$key] = [pscustomobject]@{ Table = $Watch.TableName; Columns = $added; WorkspaceResourceId = $ws; AddedAt = [datetime]::UtcNow }
|    } catch { Write-Verbose ("new-column check skipped: {0}" -f $_.Exception.Message) }
|}
|
|function Get-SILogColumnsWithValues {
|    <# PURE. Of -Columns, those holding a non-empty value in at least one row (only those can be checked). #>
|    param([AllowEmptyCollection()][object[]]$Rows = @(), [AllowEmptyCollection()][string[]]$Columns = @())
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($c in @($Columns)) {
|        foreach ($r in @($Rows)) {
|            if ($null -eq $r) { continue }
|            $v = if ($r -is [System.Collections.IDictionary]) { $r[$c] } elseif ($r.PSObject.Properties[$c]) { $r.$c } else { $null }
|            if ($null -ne $v -and -not [string]::IsNullOrWhiteSpace([string]$v)) { [void]$out.Add($c); break }
|        }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogRowColumnNames {
|    <# PURE. Every column name the rows carry (first-seen order, TimeGenerated left out: Azure sets it). #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $names = if ($r -is [System.Collections.IDictionary]) { @($r.Keys | ForEach-Object { [string]$_ }) } else { @($r.PSObject.Properties | ForEach-Object { $_.Name }) }
|        foreach ($n in $names) { if ($n -and $n -ne 'TimeGenerated' -and $seen.Add($n)) { [void]$out.Add($n) } }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogRowsCollectionTime {
|    <# PURE. The run's CollectionTime from the first row that carries one, as UTC; $null when no row does. #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $v = if ($r -is [System.Collections.IDictionary]) { $r['CollectionTime'] } elseif ($r.PSObject.Properties['CollectionTime']) { $r.CollectionTime } else { $null }
|        if ($null -eq $v -or [string]::IsNullOrWhiteSpace([string]$v)) { continue }
|        if ($v -is [datetime]) { if ($v.Kind -eq [DateTimeKind]::Local) { return $v.ToUniversalTime() }; return [datetime]::SpecifyKind($v, [DateTimeKind]::Utc) }
|        $d = [datetime]::MinValue
|        $styles = [Globalization.DateTimeStyles]::AssumeUniversal -bor [Globalization.DateTimeStyles]::AdjustToUniversal
|        if ([datetime]::TryParse([string]$v, [Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { return $d }
|    }
|    return $null
|}
|
|function Get-SILogColumnCheckKql {
|    <# PURE. Rows of this run in the table, and how many carry a value in each new column (C0, C1, ... in -Columns order). #>
|    param([Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string[]]$Columns, [AllowNull()]$CollectionTime, [AllowNull()]$PostedSince)
|    $t = ($TableName -replace '_CL$', '') -replace '[^A-Za-z0-9_]', ''
|    $agg = for ($i = 0; $i -lt $Columns.Count; $i++) {
|        'C{0} = countif(isnotempty(tostring(column_ifexists("{1}", ""))))' -f $i, ($Columns[$i] -replace '[^A-Za-z0-9_]', '')
|    }
|    $filter = if ($CollectionTime) {
|        $ct = ([datetime]$CollectionTime).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ', [Globalization.CultureInfo]::InvariantCulture)
|        "| where TimeGenerated > ago(2d)`n| where CollectionTime between (datetime($ct) - 2s .. datetime($ct) + 2s)"
|    } else {
|        $since = ([datetime]$PostedSince).ToUniversalTime().AddMinutes(-1).ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture)
|        "| where TimeGenerated >= datetime($since)"
|    }
|    "{0}_CL`n{1}`n| summarize Rows = count(), {2}" -f $t, $filter, ($agg -join ', ')
|}
|
|function Get-SILogColumnCheckVerdict {
|    <#
|        PURE. One result row of Get-SILogColumnCheckKql -> Verdict:
|          stored      -- rows arrived and every new column holds values
|          not-stored  -- rows arrived and a new column is empty on all of them (Missing names which)
|          not-landed  -- no row of this run is queryable yet
|    #>
|    param([AllowNull()]$Result, [Parameter(Mandatory)][string[]]$Columns)
|    $get = { param($n) if ($null -eq $Result) { 0 } elseif ($Result -is [System.Collections.IDictionary]) { [long]$Result[$n] } elseif ($Result.PSObject.Properties[$n]) { [long]$Result.$n } else { 0 } }
|    $rows = & $get 'Rows'
|    if ($rows -le 0) { return [pscustomobject]@{ Verdict = 'not-landed'; Rows = 0; Missing = @($Columns) } }
|    $missing = @(for ($i = 0; $i -lt $Columns.Count; $i++) { if ((& $get ('C' + $i)) -le 0) { $Columns[$i] } })
|    if ($missing.Count -gt 0) { return [pscustomobject]@{ Verdict = 'not-stored'; Rows = $rows; Missing = $missing } }
|    [pscustomobject]@{ Verdict = 'stored'; Rows = $rows; Missing = @() }
|}
|
|function Invoke-SILogLaQuery {
|    <# One Log Analytics query as the run's identity (the workspace's id read through ARM). Returns the first table's
|       rows as objects. Throws on failure. #>
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$Query, $Bound)
|    $auth = Resolve-SILogIngestAuth -Bound $Bound
|    $ws = Invoke-SILogArm -Path $WorkspaceResourceId -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth
|    $cid = if ($ws -and $ws.properties) { [string]$ws.properties.customerId } else { '' }
|    if (-not $cid) { throw 'the Log Analytics workspace id could not be read' }
|    $r = Invoke-SILogIngestRequest -Method POST -Uri ('https://api.loganalytics.io/v1/workspaces/{0}/query' -f $cid) -Body (@{ query = $Query } | ConvertTo-Json -Compress) `
|             -Resource 'https://api.loganalytics.io/' -Auth $auth -MaxAttempts 3 -What 'Log Analytics query'
|    $j = $r.Content | ConvertFrom-Json
|    $tbl = @($j.tables)[0]
|    if (-not $tbl) { return @() }
|    $names = @(@($tbl.columns) | ForEach-Object { [string]$_.name })
|    foreach ($row in @($tbl.rows)) {
|        $o = [ordered]@{}
|        for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = @($row)[$i] }
|        [pscustomobject]$o
|    }
|}
|
|function Wait-SILogColumnsStored {
|    <#
|        Asks Log Analytics, until this run's rows have arrived, whether the new columns hold their values. Polls at 30 s,
|        then 60 s, then every 120 s; stops as soon as the answer is known (stored, or every row arrived with a column
|        empty) or after -WindowSec (default 900: Azure's ingestion delay is normally seconds to a few minutes, so rows
|        that are still missing after 15 minutes are reported, not waited for). A query that fails ends the check.
|    #>
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string[]]$Columns,
|          [AllowNull()]$CollectionTime, [AllowNull()]$PostedSince, [int]$ExpectedRows = 1, $Bound, [int]$WindowSec = 0)
|    if ($WindowSec -le 0) { $WindowSec = 900; $o = 0; if ([int]::TryParse([string]$global:SI_LogIngest_NewColumnCheckSec, [ref]$o) -and $o -gt 0) { $WindowSec = $o } }
|    $kql = Get-SILogColumnCheckKql -TableName $TableName -Columns $Columns -CollectionTime $CollectionTime -PostedSince $PostedSince
|    $waited = 0; $step = 30
|    $last = [pscustomobject]@{ Verdict = 'not-landed'; Rows = 0; Missing = @($Columns) }
|    while ($true) {
|        Start-Sleep -Seconds $step
|        $waited += $step
|        try {
|            $res = @(Invoke-SILogLaQuery -WorkspaceResourceId $WorkspaceResourceId -Query $kql -Bound $Bound)
|            $last = Get-SILogColumnCheckVerdict -Result $(if ($res.Count) { $res[0] } else { $null }) -Columns $Columns
|        } catch {
|            $last = [pscustomobject]@{ Verdict = 'unverified'; Rows = 0; Missing = @($Columns); Detail = $_.Exception.Message }
|            break
|        }
|        if ($last.Verdict -eq 'stored') { break }
|        if ($last.Verdict -eq 'not-stored' -and $last.Rows -ge $ExpectedRows) { break }
|        if ($waited -ge $WindowSec) { break }
|        $step = [Math]::Min(120, $step * 2)
|    }
|    $last | Add-Member -NotePropertyName WaitedSec -NotePropertyValue $waited -Force
|    return $last
|}
|
|function Add-SILogIngestNote {
|    <# Something a publish could not deliver in full, for the run's outcome (Get-SIRunOutcome). #>
|    # -Kind 'column-lag' (#414): only NEW, non-key columns were not stored yet (Azure's propagation delay) -- the rows and
|    # their key columns are there, so a Risk Analysis run says it as a warning and is NOT partial for it.
|    param([Parameter(Mandatory)][string]$Table, [string[]]$Columns = @(), [Parameter(Mandatory)][string]$Message, [string]$Kind = 'incomplete')
|    if (-not ($global:SI_LogIngestNotes -is [System.Collections.Generic.List[object]])) { $global:SI_LogIngestNotes = New-Object System.Collections.Generic.List[object] }
|    [void]$global:SI_LogIngestNotes.Add([pscustomobject]@{ Table = $Table; Columns = @($Columns); Message = $Message; Kind = $Kind })
|}
|
|function Get-SILogIngestNoteKind {
|    <#
|        PURE. 'column-lag' when a 'not-stored' verdict misses only non-key columns; else 'incomplete'.
|        #414 / #294: the KEY columns are the ones a row cannot be placed or read without. A new key column that was not
|        stored is a real loss (the data sync refuses such rows); any other new column not stored yet is propagation lag.
|    #>
|    param([string]$Verdict, [string[]]$Missing = @())
|    $keys = @('CollectionTime', 'ConfigurationId', 'AssetId', 'AssetName', 'ReportName', 'SecuritySeverity', 'CriticalityTier', 'RiskScoreTotal', 'SolutionVersion')
|    if ($Verdict -ne 'not-stored' -or -not @($Missing).Count) { return 'incomplete' }
|    foreach ($m in @($Missing)) { if ($keys -contains ([string]$m).Trim()) { return 'incomplete' } }
|    'column-lag'
|}
|
|function Get-SILogIngestNotes {
|    if ($global:SI_LogIngestNotes -is [System.Collections.Generic.List[object]]) { return $global:SI_LogIngestNotes.ToArray() }
|    return @()
|}
|
|function Reset-SILogIngestNotes {
|    <# At the start of a run: notes and pending column checks belong to ONE run. #>
|    $global:SI_LogIngestNotes = New-Object System.Collections.Generic.List[object]
|    $global:SI_LogIngestNewColumns = @{}
|}
|
|function Confirm-SILogNewColumns {
|    <#
|        After a post through a rule that gained columns earlier in this run: were this run's values for them STORED?
|        Not stored (or not confirmable) -> one warning that says what is missing and that the next run fills it, and a
|        note that makes the run's outcome success-partial. Never throws: the rows themselves were posted.
|    #>
|    param([string]$DcrName, [string]$TableName, [AllowNull()][array]$Data, $Bound)
|    if (-not $DcrName -or -not ($global:SI_LogIngestNewColumns -is [hashtable])) { return }
|    $key = $DcrName.ToLowerInvariant()
|    if (-not $global:SI_LogIngestNewColumns.ContainsKey($key)) { return }
|    $chg = $global:SI_LogIngestNewColumns[$key]
|    $global:SI_LogIngestNewColumns.Remove($key)
|    $table = if ($TableName) { $TableName -replace '_CL$', '' } else { [string]$chg.Table }
|    try {
|        $rows = @($Data)
|        $newCols = @(Get-SILogColumnsWithValues -Rows $rows -Columns @($chg.Columns))
|        # ring 1, 2026-10-11 -- a rule CHANGED right before the post can drop values of columns it had already (added by an
|        # earlier run or job inside Azure's propagation window), not only of the columns this run added. So once this run
|        # changed the rule, EVERY column that carries a value in the posted rows is checked; the new ones first.
|        $cols = @(Get-SILogColumnsWithValues -Rows $rows -Columns @(@($newCols) + @(Get-SILogRowColumnNames -Rows $rows) | Select-Object -Unique))
|        if ($newCols.Count -eq 0 -or $cols.Count -eq 0) { return }
|        # #475: the wait (half a minute or more) is spent ONCE per table per process -- a run that posts its records in
|        # dozens of batches gained new columns batch after batch and waited every time (customer H 2026-10-09)
|        $rcache = Get-SILogIngestRunCache
|        if (-not ($rcache.ConfirmedTables -is [hashtable])) { $rcache.ConfirmedTables = @{} }
|        $tk = $table.ToLowerInvariant()
|        if ($rcache.ConfirmedTables.ContainsKey($tk)) {
|            Write-Host (" [INFO] {0}_CL gained {1} more new column(s) ({2}); this run checked the table's new columns once already, so these are not waited for -- the next run stores them in any case." -f $table, $newCols.Count, ($newCols -join ', '))
|            return
|        }
|        $rcache.ConfirmedTables[$tk] = $true
|        $b = @{}; if ($Bound) { foreach ($k in @($Bound.Keys)) { if ($k -ne 'Data') { $b[$k] = $Bound[$k] } } }
|        Write-Host (" [INFO] {0}_CL gained {1} new column(s) in this run ({2}). Azure takes a while to start storing a new column, so this run checks that the values of every column it posted ({3}) arrived ..." -f $table, $newCols.Count, ($newCols -join ', '), $cols.Count)
|        $res = Wait-SILogColumnsStored -WorkspaceResourceId ([string]$chg.WorkspaceResourceId) -TableName $table -Columns $cols `
|                   -CollectionTime (Get-SILogRowsCollectionTime -Rows $rows) -PostedSince ([datetime]::UtcNow.AddSeconds(-60)) -ExpectedRows $rows.Count -Bound $b
|        if ($res.Verdict -eq 'stored') {
|            Write-Host (" [OK]   {0}_CL: the new column(s) hold this run's values." -f $table)
|            return
|        }
|        $msg = switch ($res.Verdict) {
|            'not-stored' { "{0}_CL: the data collection rule was changed in this run and Azure was not yet storing every column when the rows arrived: this run's values for {1} are missing. The rows are there; the next run stores these columns." -f $table, (@($res.Missing) -join ', ') }
|            'not-landed' { "{0}_CL gained new column(s) in this run ({1}) and this run's rows were not queryable within {2} minutes, so it is not known whether those columns were stored." -f $table, ($cols -join ', '), [int]($res.WaitedSec / 60) }
|            default      { "{0}_CL gained new column(s) in this run ({1}) and it could not be checked whether this run's values were stored ({2})." -f $table, ($cols -join ', '), $res.Detail }
|        }
|        Write-Warning $msg
|        # the run's outcome is judged on the columns this run ADDED (as before); a column the rule already had that read
|        # back empty is said (the warning above) but only ever counts as propagation lag
|        $missNew = @(@($res.Missing) | Where-Object { $newCols -contains $_ })
|        $kind = 'column-lag'
|        if ([string]$res.Verdict -ne 'not-stored') { $kind = 'incomplete' }
|        elseif ($missNew.Count -gt 0) { $kind = Get-SILogIngestNoteKind -Verdict 'not-stored' -Missing $missNew }
|        Add-SILogIngestNote -Table $table -Columns $cols -Message $msg -Kind $kind
|    } catch {
|        $msg = ("{0}_CL gained new column(s) in this run and it could not be checked whether this run's values were stored ({1})." -f $table, $_.Exception.Message)
|        Write-Warning $msg
|        Add-SILogIngestNote -Table $table -Message $msg
|    }
|}
|
|# =====================================================================================================================
|#  THE RULE MUST DECLARE EVERY COLUMN OF THE DATA -- both engines (#294)
|#
|#  Azure stores only the columns a data collection rule DECLARES: every other value of a posted row is dropped, and the
|#  post still answers 204. Found live 2026-10-05 on ring 1: a Risk Analysis Detailed run posted 14,624 rows and only
|#  AssetName, AssetId, the report name and 8 more columns arrived -- CollectionTime, ConfigurationId, SecuritySeverity,
|#  CriticalityTier, RiskScoreTotal and SolutionVersion were EMPTY on every row, and the run logged SUCCESS. The chain:
|#    1. the run used the default rule name (its configuration had not reached the job), a rule that did not exist yet;
|#    2. AzLogDcrIngestPS creates a new rule in two steps -- first with the data's FIRST 11 columns, then with all of
|#       them. The second step was refused (InvalidTransformOutput: a column the data reads as an object, the existing
|#       table holds as text), so the rule was left with 11 columns;
|#    3. on the next run the module looked the rule up BY NAME across the tenant, found another install's same-named
|#       rule with every column, concluded nothing was missing, and the rows went through the 11-column rule.
|#  Set-SILogDcrRest stops step 2 (a new rule for an existing table is declared from the TABLE, with its
|#  types); Assert-SILogDcrCoversData stops step 3 for good: after every table/rule update it reads THE rule this install
|#  posts through (in the configured scope, never by name across the tenant), adds from the table any column of the data
|#  the rule does not declare, and REFUSES the post when a column of the data still is not declared.
|# =====================================================================================================================
|
|function Get-SILogBoundAuth {
|    <# The sign-in arguments of a wrapper call (what Set-SILogDcrRest / Resolve-SILogIngestAuth take), nothing else. #>
|    param($Bound)
|    $b = @{}
|    if ($null -eq $Bound) { return $b }
|    foreach ($k in 'AzAppId', 'AzAppSecret', 'AzAppCertificateThumbprint', 'AzAppCertificateStoreLocation', 'UseManagedIdentity', 'ManagedIdentityClientId', 'TenantId') {
|        if ($Bound.ContainsKey($k) -and $null -ne $Bound[$k] -and "$($Bound[$k])" -ne '') { $b[$k] = $Bound[$k] }
|    }
|    $b
|}
|
|function Get-SILogDataColumnNames {
|    <#
|        PURE. The columns a set of rows carries: the union over EVERY row (first-seen order, names compared without
|        letter case), without TimeGenerated and Log Analytics' own standard columns, and only names a Log Analytics
|        column can have (a name the ingest path drops before posting is not a column of the posted data).
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Rows = @())
|    $std = @('TimeGenerated', 'TenantId', 'Type', '_ResourceId', '_SubscriptionId', 'SourceSystem', 'MG', 'ManagementGroupName', '_BilledSize', '_IsBillable', '_ItemId', '_TimeReceived')
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $names = if ($r -is [System.Collections.IDictionary]) { @($r.Keys) } else { @($r.PSObject.Properties | ForEach-Object { $_.Name }) }
|        foreach ($n in $names) {
|            $s = [string]$n
|            if (-not $s -or $s -notmatch '^[A-Za-z][A-Za-z0-9_]*$' -or ($std -contains $s)) { continue }
|            if ($s.Length -gt 45) { $s = $s.Substring(0, 45) }   # the column name repair cuts a longer name to 45
|            if ($seen.Add($s)) { [void]$out.Add($s) }
|        }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogNewRuleColumns {
|    <#
|        PURE. The stream declaration of a NEW rule: the table's columns with the table's types when the table exists (then
|        each column of -SchemaSourceObject the table does not have, with its own type); else -SchemaSourceObject.
|        TimeGenerated is never declared (the rule's transform sets it).
|    #>
|    param([AllowNull()]$Table, [AllowNull()][AllowEmptyCollection()][object[]]$SchemaSourceObject = @())
|    $out = New-Object System.Collections.Generic.List[object]
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $add = { param($n, $t) $s = [string]$n; if ($s -and $s -ne 'TimeGenerated' -and $seen.Add($s)) { [void]$out.Add([ordered]@{ name = $s; type = [string]$t }) } }
|    if ($null -ne $Table -and $Table.properties -and $Table.properties.schema) {
|        foreach ($c in @($Table.properties.schema.columns)) { if ($c) { & $add $c.name $c.type } }
|    }
|    foreach ($c in @($SchemaSourceObject)) { if ($c) { & $add $c.name $c.type } }
|    return $out.ToArray()
|}
|
|function Get-SILogDcrCoverageGap {
|    <#
|        PURE. Which of -Columns the rule does NOT declare for this table's stream: Missing (all of them), InTable (those
|        the table has -- the rule can be given them from the table) and NotInTable (those the table does not have).
|    #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName, [AllowEmptyCollection()][string[]]$Columns = @(), [AllowNull()]$Table)
|    $declared = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($n in @(Get-SILogDcrStreamColumns -Dcr $Dcr -TableName $TableName)) { [void]$declared.Add([string]$n) }
|    $inTable = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    if ($null -ne $Table -and $Table.properties -and $Table.properties.schema) {
|        foreach ($c in @($Table.properties.schema.columns)) { if ($c) { [void]$inTable.Add([string]$c.name) } }
|    }
|    $missing = @(@($Columns) | Where-Object { $_ -and -not $declared.Contains([string]$_) })
|    [pscustomobject]@{
|        Missing    = $missing
|        InTable    = @($missing | Where-Object { $inTable.Contains([string]$_) })
|        NotInTable = @($missing | Where-Object { -not $inTable.Contains([string]$_) })
|    }
|}
|
|function Assert-SILogDcrCoversData {
|    <#
|        After a table/rule update: THE rule this install posts through (read in the configured scope) must declare every
|        column of -Data. Columns it lacks that the table has are added from the table (Set-SILogDcrRest, additive); a
|        column still not declared after that REFUSES the post -- throws System.IO.InvalidDataException, because Azure
|        would store the rows without it and answer success. Columns the TABLE does not have either are said and noted
|        (the run is partial), not refused: the table update is what failed there, and it says so itself.
|        Nothing is checked when schema management is off for this machine (the same rule the module applies) or the
|        rule cannot be read (said with -Verbose; Known = $false). Returns @{ Verdict; Added; Missing }.
|    #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$TableName, [string]$WorkspaceResourceId, [string]$DceName, [AllowNull()][array]$Data, $Bound)
|    $res = [pscustomobject]@{ Verdict = 'skipped'; Added = @(); Missing = @() }
|    if (-not $DcrName -or -not $TableName) { return $res }
|    if ($Bound) {
|        if ($Bound.ContainsKey('EnableUploadViaLogHub') -and [bool]$Bound['EnableUploadViaLogHub']) { return $res }
|        if ($Bound.ContainsKey('AzLogDcrTableCreateFromAnyMachine') -and -not [bool]$Bound['AzLogDcrTableCreateFromAnyMachine']) {
|            $ref = if ($Bound.ContainsKey('AzLogDcrTableCreateFromReferenceMachine')) { @($Bound['AzLogDcrTableCreateFromReferenceMachine']) } else { @() }
|            if (-not ($env:COMPUTERNAME -and ($ref -contains $env:COMPUTERNAME))) { return $res }
|        }
|    }
|    $cols = @(Get-SILogDataColumnNames -Rows @($Data))
|    if (-not $cols.Count) { return $res }
|    $t = $TableName -replace '_CL$', ''
|    $b = Get-SILogBoundAuth -Bound $Bound
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|    if (-not $st.Known) { $res.Verdict = 'unknown'; Write-Verbose ("data collection rule '{0}' could not be read -- its columns are not checked" -f $DcrName); return $res }
|    if (-not $st.Dcr) {
|        throw (New-Object System.IO.InvalidDataException(("The data collection rule '{0}' does not exist in resource group '{1}' after the table and rule update, so nothing is posted to {2}_CL." -f $DcrName, $st.ResourceGroup, $t)))
|    }
|    $auth = Resolve-SILogIngestAuth -Bound $b
|    $readTable = { try { Get-SILogTableRest -WorkspaceResourceId $WorkspaceResourceId -TableName $t -Auth $auth -NoCache } catch { $null } }
|    $table = & $readTable
|    $gap = Get-SILogDcrCoverageGap -Dcr $st.Dcr -TableName $t -Columns $cols -Table $table
|    if (-not @($gap.Missing).Count) { $res.Verdict = 'covered'; return $res }
|    if (@($gap.InTable).Count) {
|        Write-Host (" [WARN] the data collection rule '{0}' does not declare {1} column(s) of {2}_CL that this data carries ({3}) -- Azure would drop their values. Adding them to the rule from the table." -f `
|            $DcrName, @($gap.InTable).Count, $t, ((@($gap.InTable) | Select-Object -First 12) -join ', ')) -ForegroundColor Yellow
|        $null = Set-SILogDcrRest -SchemaSourceObject @(@($gap.InTable) | ForEach-Object { @{ name = [string]$_; type = 'string' } }) -AzLogWorkspaceResourceId $WorkspaceResourceId `
|                    -DceName $DceName -DcrResourceGroup ([string]$st.ResourceGroup) -DcrName $DcrName -TableName $t @b
|        $res.Added = @($gap.InTable)
|        $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|        $gap = Get-SILogDcrCoverageGap -Dcr $st.Dcr -TableName $t -Columns $cols -Table $table
|    }
|    $res.Missing = @($gap.Missing)
|    if (@($gap.InTable).Count) {
|        throw (New-Object System.IO.InvalidDataException(("The data collection rule '{0}' does not declare {1} column(s) of {2}_CL that this data carries ({3}) and they could not be added to it. Posting through it would store the rows WITHOUT those values, so nothing is posted." -f `
|            $DcrName, @($gap.InTable).Count, $t, ((@($gap.InTable) | Select-Object -First 20) -join ', '))))
|    }
|    if (@($gap.NotInTable).Count) {
|        $msg = ("{0}_CL does not have {1} column(s) this data carries ({2}), so their values are not stored by this run." -f $t, @($gap.NotInTable).Count, ((@($gap.NotInTable) | Select-Object -First 20) -join ', '))
|        Write-Warning $msg
|        Add-SILogIngestNote -Table $t -Columns @($gap.NotInTable) -Message $msg
|        $res.Verdict = 'partial'
|        return $res
|    }
|    $res.Verdict = 'repaired'
|    return $res
|}
|
|# =====================================================================================================================
|#  REST: run cache, HTTP seam, tokens
|# =====================================================================================================================
|
|function Get-SILogIngestRunCache {
|    <# Per-run (per-process) cache: tokens, ARM reads, DCR ids. Global because this file is dot-sourced at different
|       depths by different engines, and `$script:` would then be a different scope per caller. #>
|    if (-not ($global:SI_LogIngestRunCache -is [hashtable])) {
|        $global:SI_LogIngestRunCache = @{ Tokens = @{}; Arm = @{}; DcrIds = @{} }
|    }
|    return $global:SI_LogIngestRunCache
|}
|
|function Reset-SILogIngestArmCache {
|    <# After any create/update: the next read must see what was just written. #>
|    $c = Get-SILogIngestRunCache
|    $c.Arm = @{}
|}
|
|function Invoke-SILogIngestHttp {
|    <#
|        THE ONE HTTP SEAM. Every REST call in this file goes through here (tests Mock it). Never throws on an HTTP status:
|        returns @{ StatusCode; Content; RetryAfter }. A network failure (no response at all) is StatusCode 0.
|        HttpWebRequest, not Invoke-WebRequest: its error shape is the same on PS 5.1 and pwsh 7, so the body of a 4xx
|        and the Retry-After of a 429 are read the same way on both.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Method,
|        [Parameter(Mandatory)][string]$Uri,
|        [hashtable]$Headers,
|        $Body,
|        [string]$ContentType,
|        [int]$TimeoutSec = 300
|    )
|    if ($PSVersionTable.PSEdition -ne 'Core') {
|        # Windows PowerShell 5.1 on an older .NET Framework may not offer TLS 1.2 by default; Azure requires it.
|        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
|    }
|    $req = [System.Net.HttpWebRequest]::Create($Uri)
|    $req.Method = $Method.ToUpperInvariant()
|    $req.Timeout = $TimeoutSec * 1000
|    $req.ReadWriteTimeout = $TimeoutSec * 1000
|    $req.Accept = 'application/json'
|    if ($Headers) {
|        foreach ($k in $Headers.Keys) {
|            if ($k -eq 'Content-Type') { $req.ContentType = [string]$Headers[$k] }
|            elseif ($k -eq 'Accept')   { $req.Accept = [string]$Headers[$k] }
|            else { $req.Headers[$k] = [string]$Headers[$k] }
|        }
|    }
|    if ($ContentType) { $req.ContentType = $ContentType }
|    if ($null -ne $Body) {
|        # statements, never `= if (...) { $Body }`: an if-expression enumerates a byte array into object[]
|        [byte[]]$bytes = $null
|        if ($Body -is [byte[]]) { $bytes = $Body } else { $bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$Body) }
|        $req.ContentLength = $bytes.Length
|        $s = $req.GetRequestStream()
|        try { $s.Write($bytes, 0, $bytes.Length) } finally { $s.Close() }
|    } elseif ($req.Method -in 'POST', 'PUT', 'PATCH') {
|        $req.ContentLength = 0
|    }
|    $resp = $null
|    try { $resp = $req.GetResponse() }
|    catch {
|        $we = $_.Exception
|        while ($we -and -not ($we -is [System.Net.WebException])) { $we = $we.InnerException }
|        if ($we -and $we.Response) {
|            $resp = $we.Response
|            # An HTTP status is an answer returned to the caller, not an error of this process: take the caught record
|            # back out of $Error (setup shows every new entry -- each probe printed "(404) Not Found", 2026-10-06).
|            if ($global:Error.Count -gt 0 -and [object]::ReferenceEquals($global:Error[0], $_)) { $global:Error.RemoveAt(0) }
|        }
|        else { return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; RetryAfter = $null } }
|    }
|    try {
|        $text = ''
|        $rs = $resp.GetResponseStream()
|        if ($rs) { $sr = New-Object System.IO.StreamReader($rs); try { $text = $sr.ReadToEnd() } finally { $sr.Close() } }
|        return [pscustomobject]@{ StatusCode = [int]$resp.StatusCode; Content = $text; RetryAfter = [string]$resp.Headers['Retry-After'] }
|    } finally { $resp.Close() }
|}
|
|function Initialize-SILogIngestAuthHelpers {
|    <# The managed-identity and certificate token helpers live in auth/. Loaded on first need, never at file load. #>
|    # Only what is MISSING is loaded, and only that is published to the global scope (it was dot-sourced inside this
|    # function, so it would vanish on return). Something already visible -- the engine's own copy, a test's mock -- is
|    # never replaced.
|    $authDir = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth'
|    # The managed-identity helper is NOT loaded here: the run's entry point loads it (the launcher config on a VM / Arc
|    # server, the container entry in a job) -- an engine never does (SIv3-ContainerIdentity). Get-SILogIngestToken
|    # says so when it is missing.
|    $want = @(
|        @{ File = 'Find-SICertificate.ps1'; Fns = @('Get-SICertificateClientToken', 'Get-SICertificateFromStore', 'Test-SICertDriveAvailable') }
|    )
|    foreach ($w in $want) {
|        $missing = @($w.Fns | Where-Object { -not (Get-Command -Name $_ -ErrorAction Ignore) })
|        if ($missing.Count -eq 0) { continue }
|        $p = Join-Path $authDir $w.File
|        if (-not (Test-Path -LiteralPath $p)) { continue }
|        . $p
|        foreach ($n in $missing) {
|            $f = Get-Command -Name $n -CommandType Function -ErrorAction Ignore
|            if ($f) { Set-Item -Path ("function:global:{0}" -f $n) -Value $f.ScriptBlock }
|        }
|    }
|}
|
|function Resolve-SILogIngestAuth {
|    <#
|        The sign-in the call site handed over (the same splat AzLogDcrIngestPS takes), as one decision:
|          ManagedIdentity -- UseManagedIdentity = $true
|          Certificate     -- AzAppId + AzAppCertificateThumbprint + TenantId
|          Secret          -- AzAppId + AzAppSecret + TenantId
|          then the run's own decision: $global:SI_UseManagedIdentity (#222) -> ManagedIdentity, else the run's own
|          sign-in (Resolve-SIAzRestAuth: what Connect-SIAzAccount recorded, else the configured identity).
|        Same precedence as the module: managed identity, then certificate, then secret.
|    #>
|    param($Bound = @{})   # a hashtable or $PSBoundParameters
|    if ($null -eq $Bound) { $Bound = @{} }
|    $g = { param($k) if ($Bound.ContainsKey($k)) { $Bound[$k] } else { $null } }
|    $mi = & $g 'UseManagedIdentity'
|    if ($null -eq $mi -and $null -ne (Get-Variable -Scope Global -Name UseManagedIdentityDefault -ValueOnly -ErrorAction Ignore)) { $mi = (Get-Variable -Scope Global -Name UseManagedIdentityDefault -ValueOnly -ErrorAction Ignore) }
|    $app = [string](& $g 'AzAppId'); $tid = [string](& $g 'TenantId')
|    $thumb = [string](& $g 'AzAppCertificateThumbprint'); $sec = [string](& $g 'AzAppSecret')
|    if ([bool]$mi) {
|        $cid = [string](& $g 'ManagedIdentityClientId'); if (-not $cid) { $cid = [string](Get-Variable -Scope Global -Name SI_UAMI_ClientId -ValueOnly -ErrorAction Ignore) }
|        return @{ Mode = 'ManagedIdentity'; ClientId = $cid }
|    }
|    if ($app -and $thumb -and $tid) { return @{ Mode = 'Certificate'; AppId = $app; TenantId = $tid; Thumbprint = ($thumb -replace '\s', '') } }
|    if ($app -and $sec -and $tid)   { return @{ Mode = 'Secret'; AppId = $app; TenantId = $tid; Secret = $sec } }
|    if ((Get-Variable -Scope Global -Name SI_UseManagedIdentity -ValueOnly -ErrorAction Ignore) -eq $true) { return @{ Mode = 'ManagedIdentity'; ClientId = [string](Get-Variable -Scope Global -Name SI_UAMI_ClientId -ValueOnly -ErrorAction Ignore) } }
|    return @{ Mode = 'Run' }
|}
|
|function Get-SILogIngestToken {
|    <#
|        A bearer token for -Resource (https://monitor.azure.com/ for ingestion, https://management.azure.com/ for ARM),
|        as the identity -Auth (Resolve-SILogIngestAuth) names:
|          ManagedIdentity -- Get-SIManagedIdentityToken (container / Azure VM / Azure Arc endpoint; its own cache)
|          Certificate     -- Get-SICertificateClientToken (JWT client assertion signed from the X509Store; no Cert: drive)
|          Secret          -- client_credentials with the secret
|          Support         -- the Invardia support session's Get-InvardiaSupportToken (#524; SI-AzRest.ps1 Get-SISupportToken)
|          Run             -- the run's own sign-in (Resolve-SIAzRestAuth, over REST; #524: never an Azure session)
|        Cached per identity + resource until 5 minutes before expiry.
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [hashtable]$Auth, [switch]$ForceRefresh)
|    # the supported token hook (see SI-AzRest.ps1): consulted first when set and no explicit sign-in was handed over
|    if (-not $Auth) {
|        $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|        if ($tp -is [scriptblock]) { $pt = [string](& $tp $Resource); if (-not [string]::IsNullOrWhiteSpace($pt)) { return $pt } }
|        $Auth = Resolve-SILogIngestAuth
|    }
|    $res = $Resource.TrimEnd('/') + '/'
|    # #524: the Invardia support session's tokens (Resolve-SIAzRestAuth's Mode 'Support') -- Invardia caches them; the
|    # tenant of each is checked against the one SI works in
|    if ($Auth.Mode -eq 'Support') { return (Get-SISupportToken -Resource $res -TenantId ([string]$Auth.TenantId) -ForceRefresh:$ForceRefresh) }
|    $cache = (Get-SILogIngestRunCache).Tokens
|    $who = switch ($Auth.Mode) { 'Certificate' { $Auth.AppId } 'Secret' { $Auth.AppId } 'ManagedIdentity' { $Auth.ClientId } default { '' } }
|    $key = '{0}|{1}|{2}' -f $Auth.Mode, $who, $res
|    if (-not $ForceRefresh -and $cache.ContainsKey($key) -and $cache[$key].ExpiresAt -gt [datetime]::UtcNow) { return $cache[$key].Token }
|
|    $token = $null; $expiresAt = [datetime]::UtcNow.AddMinutes(45)
|    # A TRANSIENT failure of the token endpoint (the managed-identity endpoint of a container, Entra) is waited out and asked
|    # again, a bounded number of times -- Microsoft's errors (Get-SITransientKind: throttled / timeout / unavailable). Any
|    # other answer (a refused sign-in, a missing certificate) fails at once, as before. The sweep of 2026-10-22: one
|    # IDENTITY_ENDPOINT blip threw through every helper's retry and failed the run.
|    if (-not (Get-Command -Name Get-SITransientKind -ErrorAction Ignore)) { . (Join-Path $PSScriptRoot 'SI-ErrorClass.ps1') }
|    $tokenAttempts = 4
|    for ($tokenTry = 1; $tokenTry -le $tokenAttempts; $tokenTry++) {
|    try {
|    switch ($Auth.Mode) {
|        'ManagedIdentity' {
|            if (-not (Get-Command -Name Get-SIManagedIdentityToken -ErrorAction Ignore)) {
|                throw 'Sign-in as a managed identity was asked for, but the managed-identity sign-in helper is not loaded in this run (its entry point loads it: the launcher configuration or the container entry).'
|            }
|            $token = Get-SIManagedIdentityToken -Resource $res -ClientId ([string]$Auth.ClientId) -ForceRefresh:$ForceRefresh
|        }
|        'Certificate' {
|            Initialize-SILogIngestAuthHelpers
|            $token = Get-SICertificateClientToken -TenantId $Auth.TenantId -ClientId $Auth.AppId -Thumbprint $Auth.Thumbprint -Resource $res
|        }
|        'Secret' {
|            $body = 'client_id={0}&scope={1}&client_secret={2}&grant_type=client_credentials' -f `
|                [uri]::EscapeDataString($Auth.AppId), [uri]::EscapeDataString($res.TrimEnd('/') + '/.default'), [uri]::EscapeDataString($Auth.Secret)
|            $r = Invoke-SILogIngestHttp -Method POST -Uri ('https://login.microsoftonline.com/{0}/oauth2/v2.0/token' -f $Auth.TenantId) `
|                     -Body $body -ContentType 'application/x-www-form-urlencoded'
|            if ([int]$r.StatusCode -lt 200 -or [int]$r.StatusCode -ge 300) {
|                throw ("Sign-in with the client secret failed for {0}. HTTP Status: {1} Response: {2}" -f $res, $r.StatusCode, $r.Content)
|            }
|            $j = $r.Content | ConvertFrom-Json
|            $token = [string]$j.access_token
|            $secs = 0
|            if ([int]::TryParse([string]$j.expires_in, [ref]$secs) -and $secs -gt 600) { $expiresAt = [datetime]::UtcNow.AddSeconds($secs - 300) }
|        }
|        default {
|            $t = Get-SIAzAccessToken -ResourceUrl $res -ErrorAction Stop
|            $token = if ($t.Token -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $t.Token).Password } else { [string]$t.Token }
|            try { if ($t.ExpiresOn) { $e = ([DateTimeOffset]$t.ExpiresOn).UtcDateTime.AddMinutes(-5); if ($e -lt $expiresAt) { $expiresAt = $e } } } catch { }
|        }
|    }
|    break
|    } catch {
|        $kind = Get-SITransientKind -Message ([string]$_.Exception.Message)
|        if ($kind -eq 'error' -or $tokenTry -ge $tokenAttempts) { throw }
|        $wait = Get-SILogIngestRetryDelay -RetryAfter '' -Attempt $tokenTry
|        Write-Verbose ("The token for {0} ({1} sign-in) was not issued ({2}: {3}) -- asked again in {4} s ({5}/{6})." -f $res, $Auth.Mode, $kind, $_.Exception.Message, $wait, $tokenTry, $tokenAttempts)
|        Start-Sleep -Seconds $wait
|    }
|    }
|    if ([string]::IsNullOrWhiteSpace($token)) { throw ("No access token for {0} ({1} sign-in)." -f $res, $Auth.Mode) }
|    $cache[$key] = @{ Token = $token; ExpiresAt = $expiresAt }
|    return $token
|}
|
|function Get-SILogIngestRetryDelay {
|    <# Seconds to wait before retry -Attempt: the server's Retry-After (seconds or an HTTP date) when it sent one,
|       else exponential (2, 4, 8 ... capped at 60). Never more than 10 minutes: a wait the server asks for had no upper
|       limit, and a run that waits says nothing meanwhile (the retry after it either works or is the answer). #>
|    param([string]$RetryAfter, [int]$Attempt)
|    $s = 0
|    if ($RetryAfter) {
|        if ([int]::TryParse($RetryAfter.Trim(), [ref]$s)) { return [Math]::Min(600, [Math]::Max(1, $s)) }
|        $d = [datetime]::MinValue
|        if ([datetime]::TryParse($RetryAfter, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::AdjustToUniversal, [ref]$d)) {
|            return [int][Math]::Min(600, [Math]::Max(1, [Math]::Ceiling(($d - [datetime]::UtcNow).TotalSeconds)))
|        }
|    }
|    return [int][Math]::Min(60, [Math]::Pow(2, $Attempt))
|}
|
|function Invoke-SILogIngestRequest {
|    <#
|        One authenticated REST call with the retry rule (CLAUDE.md working rule 4):
|          429 / 408 / 5xx / no response -> PLATFORM: wait (Retry-After when sent) and retry in-run
|          401 once                      -> the token is refreshed and the call repeated once
|          404 with -AllowNotFound       -> $null (a lookup that found nothing)
|          any other 4xx                 -> FAIL FAST, the response body in the error: re-sending an invalid request
|                                           burns time and fails identically
|        Returns the response object (StatusCode / Content).
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Uri,
|        $Body,
|        [string]$ContentType = 'application/json',
|        [hashtable]$Headers,
|        [string]$Resource = 'https://management.azure.com/',
|        [hashtable]$Auth,
|        [switch]$AllowNotFound,
|        [int]$MaxAttempts = 6,
|        [string]$What = 'Azure Resource Manager request'
|    )
|    $refreshed = $false; $forceNext = $false
|    for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
|        $token = Get-SILogIngestToken -Resource $Resource -Auth $Auth -ForceRefresh:$forceNext
|        $forceNext = $false
|        $h = @{ 'Authorization' = ('Bearer ' + $token) }
|        if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|        $r = Invoke-SILogIngestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType
|        $code = [int]$r.StatusCode
|        if ($code -ge 200 -and $code -lt 300) { return $r }
|        if ($code -eq 404 -and $AllowNotFound) { return $null }
|        if ($code -eq 401 -and -not $refreshed) { $refreshed = $true; $forceNext = $true; continue }
|        $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|        if ($transient -and $attempt -lt $MaxAttempts) {
|            $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|            Write-Verbose ("{0}: HTTP {1}, retrying in {2}s (attempt {3}/{4})" -f $What, $code, $wait, $attempt, $MaxAttempts)
|            # SAID, not only in the verbose stream (which the publish path switches off): a call that got no answer can
|            # have taken 5 minutes already, and six of them in a row were half an hour without one line in the run log
|            if ($code -eq 0 -or $wait -ge 30) {
|                Write-Host (" [INFO] {0}: {1} -- trying again in {2} second(s) (attempt {3} of {4})" -f $What, $(if ($code -eq 0) { 'no answer from Azure' } else { 'Azure answered HTTP {0}' -f $code }), $wait, $attempt, $MaxAttempts)
|            }
|            Start-Sleep -Seconds $wait
|            continue
|        }
|        throw ("{0} failed. HTTP Status: {1} Response: {2}" -f $What, $code, $r.Content)
|    }
|    throw ("{0} failed after {1} attempts." -f $What, $MaxAttempts)
|}
|
|# =====================================================================================================================
|#  REST: ARM reads/writes, scoped lookups
|# =====================================================================================================================
|
|function Get-SILogArmApiVersion {
|    <# ARM api-versions this file uses (a function, not a variable: the file is dot-sourced at different depths). #>
|    param([Parameter(Mandatory)][ValidateSet('Dce', 'Dcr', 'Table', 'Role')][string]$Kind)
|    switch ($Kind) { 'Dce' { '2022-06-01' } 'Dcr' { '2022-06-01' } 'Table' { '2022-10-01' } 'Role' { '2022-04-01' } }
|}
|
|function Invoke-SILogArm {
|    <# ARM call -> parsed JSON (or $null for a 404 with -AllowNotFound). GETs are cached per run; any write clears it. #>
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$ApiVersion, $Body, [hashtable]$Auth, [switch]$AllowNotFound, [switch]$NoCache)
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path + $(if ($Path -match '\?') { '&' } else { '?' }) + 'api-version=' + $ApiVersion }
|    $cache = (Get-SILogIngestRunCache).Arm
|    if ($Method -eq 'GET' -and -not $NoCache -and $cache.ContainsKey($uri)) { return $cache[$uri] }
|    $json = if ($null -ne $Body -and -not ($Body -is [string])) { $Body | ConvertTo-Json -Depth 50 -Compress } else { $Body }
|    $r = Invoke-SILogIngestRequest -Method $Method -Uri $uri -Body $json -Auth $Auth -AllowNotFound:$AllowNotFound -What ('Azure Resource Manager {0} {1}' -f $Method, ($uri -replace '\?.*$', ''))
|    $obj = $null
|    if ($r -and -not [string]::IsNullOrWhiteSpace([string]$r.Content)) { $obj = $r.Content | ConvertFrom-Json }
|    if ($Method -eq 'GET') { if (-not $NoCache) { $cache[$uri] = $obj } } else { Reset-SILogIngestArmCache }
|    return $obj
|}
|
|function Get-SILogArmList {
|    <# Every item of an ARM list, following nextLink. #>
|    param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$ApiVersion, [hashtable]$Auth)
|    $items = New-Object 'System.Collections.Generic.List[object]'
|    $page = Invoke-SILogArm -Path $Path -ApiVersion $ApiVersion -Auth $Auth
|    while ($page) {
|        foreach ($v in @($page.value)) { if ($null -ne $v) { [void]$items.Add($v) } }
|        if ([string]::IsNullOrWhiteSpace([string]$page.nextLink)) { break }
|        $page = Invoke-SILogArm -Path ([string]$page.nextLink) -ApiVersion $ApiVersion -Auth $Auth
|    }
|    foreach ($i in $items) {
|        # the Resource Graph shape callers already read (subscriptionId / resourceGroup) -- ARM omits them
|        if ([string]$i.id -match '^/subscriptions/([^/]+)/resourceGroups/([^/]+)/') {
|            if (-not $i.PSObject.Properties['subscriptionId']) { $i | Add-Member -NotePropertyName subscriptionId -NotePropertyValue $Matches[1] }
|            if (-not $i.PSObject.Properties['resourceGroup'])  { $i | Add-Member -NotePropertyName resourceGroup -NotePropertyValue $Matches[2] }
|        }
|    }
|    return $items.ToArray()   # enumerated, like the module's list; callers wrap in @()
|}
|
|function Get-SILogIngestScope {
|    <#
|        WHERE this install's endpoint and rules live: subscription + resource groups. Lookups are by NAME within this
|        scope, never tenant-wide -- the same name exists in other environments (measured 2026-10-01: three endpoints
|        named dce-securityinsight in two subscriptions).
|          Subscription  -SubscriptionId, else -WorkspaceResourceId's, else SI_AzSubscriptionId, else SI_WorkspaceResourceId's,
|                        else the 2.2.x SubscriptionId (a new rule is created in the workspace's subscription, as the
|                        module did; SI_AzSubscriptionId is filled from the workspace by Initialize-SIIngestGlobals)
|          DcrRg         -DcrResourceGroup, else SI_DcrResourceGroup
|          DceRg         -DceResourceGroup, else SI_DceResourceGroup, else the DCR resource group
|    #>
|    param([string]$SubscriptionId, [string]$WorkspaceResourceId, [string]$DcrResourceGroup, [string]$DceResourceGroup)
|    $sub = $SubscriptionId
|    if (-not $sub -and $WorkspaceResourceId -match '/subscriptions/([^/]+)/') { $sub = $Matches[1] }
|    if (-not $sub) { $sub = [string]$global:SI_AzSubscriptionId }
|    if (-not $sub -and "$($global:SI_WorkspaceResourceId)" -match '/subscriptions/([^/]+)/') { $sub = $Matches[1] }
|    if (-not $sub) { $sub = [string]$global:SubscriptionId }
|    $dcrRg = if ($DcrResourceGroup) { $DcrResourceGroup } else { [string]$global:SI_DcrResourceGroup }
|    $dceRg = if ($DceResourceGroup) { $DceResourceGroup } elseif ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup } else { $dcrRg }
|    [pscustomobject]@{ Subscription = $sub; DcrRg = $dcrRg; DceRg = $dceRg }
|}
|
|function Get-SILogScopedList {
|    param([ValidateSet('Dce', 'Dcr')][string]$Kind, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth)
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) {
|        throw ("No subscription is configured for the data collection {0} lookup (SI_AzSubscriptionId / SI_WorkspaceResourceId). It is never read tenant-wide, because the same name exists in other environments." -f $(if ($Kind -eq 'Dce') { 'endpoint' } else { 'rule' }))
|    }
|    $type = if ($Kind -eq 'Dce') { 'dataCollectionEndpoints' } else { 'dataCollectionRules' }
|    $path = if ($ResourceGroup) { "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/$type" }
|            else { "/subscriptions/$SubscriptionId/providers/Microsoft.Insights/$type" }
|    return (Get-SILogArmList -Path $path -ApiVersion (Get-SILogArmApiVersion $Kind) -Auth $Auth)
|}
|
|function Get-SIDceListRest {
|    <# REST twin of Get-AzDceListAll -- but SCOPED: the configured subscription only (never tenant-wide). Same auth
|       arguments as the module; -SubscriptionId / -ResourceGroup narrow further. #>
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId
|    return (Get-SILogScopedList -Kind Dce -SubscriptionId $scope.Subscription -ResourceGroup $ResourceGroup -Auth $auth)
|}
|
|function Get-SIDcrListRest {
|    <# REST twin of Get-AzDcrListAll -- scoped to the configured subscription, like Get-SIDceListRest. #>
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId
|    return (Get-SILogScopedList -Kind Dcr -SubscriptionId $scope.Subscription -ResourceGroup $ResourceGroup -Auth $auth)
|}
|
|function Find-SILogResourceByName {
|    <#
|        A DCR or DCE by NAME in the configured scope:
|          resource group known  -> exactly that resource (GET by its id); nothing else is considered
|          resource group absent -> the subscription's list; one match is used, several refuse (the name is ambiguous)
|        -AnyResourceGroupWhenMissing (endpoints only): not in the resource group, but exactly ONE of that name in the
|        subscription -> that one (an endpoint outside the rules' resource group has always worked); several refuse.
|        Returns $null when there is none.
|    #>
|    param([ValidateSet('Dce', 'Dcr')][string]$Kind, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth, [switch]$AnyResourceGroupWhenMissing)
|    $label = if ($Kind -eq 'Dce') { 'data collection endpoint' } else { 'data collection rule' }
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) { throw ("No subscription is configured to look up {0} '{1}' in (SI_AzSubscriptionId / SI_WorkspaceResourceId)." -f $label, $Name) }
|    $type = if ($Kind -eq 'Dce') { 'dataCollectionEndpoints' } else { 'dataCollectionRules' }
|    if ($ResourceGroup) {
|        $hit = Invoke-SILogArm -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/$type/$Name" -ApiVersion (Get-SILogArmApiVersion $Kind) -Auth $Auth -AllowNotFound
|        if ($hit -or -not $AnyResourceGroupWhenMissing) { return $hit }
|    }
|    $same = @(Get-SILogScopedList -Kind $Kind -SubscriptionId $SubscriptionId -Auth $Auth | Where-Object { $_ -and $_.name -eq $Name })
|    if ($same.Count -eq 1) { return $same[0] }
|    if ($same.Count -gt 1) {
|        throw ("{0} '{1}' exists {2} times in subscription '{3}'{4}, so nothing was posted -- set the resource group this install uses ({5})." -f `
|            $label, $Name, $same.Count, $SubscriptionId, $(if ($ResourceGroup) { " (none in resource group '$ResourceGroup')" } else { '' }),
|            $(if ($Kind -eq 'Dce') { 'SI_DceResourceGroup' } else { 'SI_DcrResourceGroup' }))
|    }
|    return $null
|}
|
|# =====================================================================================================================
|#  REST: data shape -- exact twins of the module's pre-processing (so 'Rest' declares and posts the same columns)
|# =====================================================================================================================
|
|function Add-SICollectionTimeRest {
|    <#
|        CollectionTime on every row, IDENTICAL across all shards and batches of one run:
|          * a row that already carries a CollectionTime keeps it -- the engines stamp the run's own value upstream
|            ($RunContext.CollectionTime / $global:RA_CollectionTime), and that is the value every shard shares;
|          * a row without one gets this process's run value, minted once and reused by every later call.
|        Same value format as the module ([datetime] from "yyyy-MM-ddTHH:mm:ssK", UTC).
|        DIFFERS FROM THE MODULE ON PURPOSE: Add-CollectionTimeToAllEntriesInArray overwrites every row with the time
|        of THAT call, so a "safety net" call after the upstream stamp replaced the shared run value.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    if (-not ($global:SI_LogIngestRunCollectionTime -is [datetime])) {
|        [datetime]$ct = (Get-Date ([datetime]::Now.ToUniversalTime()) -Format 'yyyy-MM-ddTHH:mm:ssK')
|        $global:SI_LogIngestRunCollectionTime = $ct
|    }
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($e in $Data) {
|        $p = $e.PSObject.Properties['CollectionTime']
|        if (-not $p -or $null -eq $p.Value -or [string]::IsNullOrWhiteSpace([string]$p.Value)) {
|            $e | Add-Member -MemberType NoteProperty -Name CollectionTime -Value $global:SI_LogIngestRunCollectionTime -Force | Out-Null
|        }
|        [void]$out.Add($e)
|    }
|    return [array]$out.ToArray()
|}
|
|function Add-SIColumnDataRest {
|    <# Twin of Add-ColumnDataToAllEntriesInArray: up to three columns with one value each, on every row. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [Parameter(Mandatory)][string]$Column1Name, [Parameter(Mandatory)][AllowEmptyString()][string]$Column1Data,
|          [string]$Column2Name, [string]$Column2Data, [string]$Column3Name, [string]$Column3Data)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($e in $Data) {
|        if ($Column1Name) { $e | Add-Member -MemberType NoteProperty -Name $Column1Name -Value $Column1Data -Force }
|        if ($Column2Name) { $e | Add-Member -MemberType NoteProperty -Name $Column2Name -Value $Column2Data -Force }
|        if ($Column3Name) { $e | Add-Member -MemberType NoteProperty -Name $Column3Name -Value $Column3Data -Force }
|        [void]$out.Add($e)
|    }
|    return [array]$out.ToArray()
|}
|
|function Repair-SILogColumnNameRest {
|    <# Twin of ValidateFix-AzLogAnalyticsTableSchemaColumnNames (1.7.x): prohibited names get '_', ':' '-' '.' are
|       removed, leading '_' trimmed, leading whitespace trimmed, >45 characters cut; renamed columns move to the end
|       of the row with their own values. Rows are rebuilt only when a name needs fixing. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    $prohibited = @('_ResourceId', 'id', '_ResourceId', '_SubscriptionId', 'TenantId', 'Type', 'UniqueId', 'Title', 'Date')
|    $checked = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $rename = @{}
|    foreach ($e in $Data) {
|        foreach ($p in $e.PSObject.Properties) {
|            $n = $p.Name
|            if (-not $checked.Add($n)) { continue }
|            if ($n -in $prohibited)     { $rename[$n] = $n + '_' }
|            elseif ($n -like '*:*')     { $rename[$n] = $n.Replace(':', '') }
|            elseif ($n -like '*-*')     { $rename[$n] = $n.Replace('-', '') }
|            elseif ($n -like '*.*')     { $rename[$n] = $n.Replace('.', '') }
|            elseif ($n -like '_*')      { $rename[$n] = $n.TrimStart('_') }
|            elseif ($n -like '* *')     { $rename[$n] = $n.TrimStart() }
|            elseif ($n.Length -gt 45)   { $rename[$n] = $n.Substring(0, 45) }
|        }
|    }
|    if ($rename.Count -eq 0) { return [array]$Data }
|    # #639: only a row that CARRIES a name to fix is rebuilt (a copy of that row); every other row is passed on as it is --
|    # never a copy of the whole post. (Not in place: the caller may still read the row by its own names.)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($row in $Data) {
|        $needs = $false
|        foreach ($p in $row.PSObject.Properties) { if ($rename.ContainsKey($p.Name)) { $needs = $true; break } }
|        if (-not $needs) { [void]$out.Add($row); continue }
|        $rebuilt = [ordered]@{}
|        $moved = New-Object 'System.Collections.Generic.List[object]'
|        foreach ($p in $row.PSObject.Properties) {
|            if ($rename.ContainsKey($p.Name)) { [void]$moved.Add($p) } else { $rebuilt[$p.Name] = $p.Value }
|        }
|        foreach ($p in $moved) { $rebuilt[[string]$rename[$p.Name]] = $p.Value }
|        [void]$out.Add([pscustomobject]$rebuilt)
|    }
|    return [array]$out.ToArray()
|}
|
|function Get-SILogSchemaRest {
|    <#
|        Twin of Get-ObjectSchemaAsArray (-As Array) and Get-ObjectSchemaAsHash (-As Hash): the column list of the
|        WHOLE set, each column's type from the first row that carries it, read the way the module reads it -- the row
|        is round-tripped through JSON and the type taken from Get-Member's definition:
|            int* / real* -> int    long* -> long    guid* -> dynamic    string* -> string    datetime* -> datetime
|            bool* -> boolean       object* / PSCustomObject -> dynamic
|        DIFFERENCES FROM THE MODULE (2026-10-11, both made Log Analytics discard values):
|          * a fractional number is `real` -- the module matched none of its patterns and INHERITED the type of the column
|            read just before it (alphabetically), which is how LastSignInDays became datetime;
|          * an empty (null) value does not decide the type: the first row with a value does, 'dynamic' if none has one.
|        KNOWN TRAP KEPT:
|          * 'int' vs 'long' follows the value's size in the first row that has the column.
|        -ReturnType Table adds TimeGenerated (datetime) first and a description per column; DCR (the default for Array)
|        has name + type only. -As Hash returns hashtables and, like the module, nothing without -ReturnType.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [ValidateSet('Array', 'Hash')][string]$As = 'Array', [ValidateSet('Table', 'DCR')][string[]]$ReturnType)
|    $table = New-Object 'System.Collections.Generic.List[object]'
|    $dcr   = New-Object 'System.Collections.Generic.List[object]'
|    $seen  = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    [void]$seen.Add('TimeGenerated')
|    # the module's shapes: Array -> PSCustomObject, Hash -> plain hashtable
|    $mk = { param($n, $t, [switch]$Desc)
|        if ($As -eq 'Hash') { if ($Desc) { @{ name = $n; type = $t; description = '' } } else { @{ name = $n; type = $t } } }
|        elseif ($Desc) { [pscustomobject]@{ name = $n; type = $t; description = '' } }
|        else { [pscustomobject]@{ name = $n; type = $t } }
|    }
|    [void]$table.Add((& $mk 'TimeGenerated' 'datetime' -Desc))
|    # columns seen so far only EMPTY (null): typed from the first row that has a value, 'dynamic' when none has
|    $nullOnly = New-Object 'System.Collections.Generic.List[string]'
|    $nullSet  = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($entry in $Data) {
|        $hasNew = $false
|        foreach ($p in $entry.PSObject.Properties) { if (-not $seen.Contains($p.Name) -and ($null -ne $p.Value -or -not $nullSet.Contains($p.Name))) { $hasNew = $true; break } }
|        if (-not $hasNew) { continue }
|        $cols = $entry | ConvertTo-Json -Depth 100 | ConvertFrom-Json | Get-Member -MemberType NoteProperty
|        foreach ($c in $cols) {
|            if ($seen.Contains($c.Name)) { continue }
|            $d = [string]$c.Definition
|            # ring 1, 2026-10-11 -- THE TYPE IS DECIDED PER COLUMN, NEVER INHERITED. The module's mapping kept the previous
|            # column's type for a definition it did not know (a double), and Get-Member lists the columns alphabetically,
|            # so LastSignInDays (a double) was declared after LastSignInDateTime: datetime -- and every value of it was then
|            # discarded by Log Analytics. A fractional number is `real`; an empty value waits for a row that has one.
|            $objType = $null
|            if ($d -match '^(?i)(System\.)?Object\s') {   # a null value round-trips as "object <name>=null"
|                if ($nullSet.Add($c.Name)) { [void]$nullOnly.Add($c.Name) }
|                continue
|            }
|            if     ($d -like 'int*')      { $objType = 'int' }
|            elseif ($d -like 'real*')     { $objType = 'int' }
|            elseif ($d -like 'long*')     { $objType = 'long' }
|            elseif ($d -like 'double*' -or $d -like 'decimal*' -or $d -like 'float*' -or $d -like 'single*') { $objType = 'real' }
|            elseif ($d -like 'guid*')     { $objType = 'dynamic' }
|            elseif ($d -like 'string*')   { $objType = 'string' }
|            elseif ($d -like 'datetime*') { $objType = 'datetime' }
|            elseif ($d -like 'bool*')     { $objType = 'boolean' }
|            elseif ($d -like 'object*')   { $objType = 'dynamic' }
|            elseif ($d -like 'System.Management.Automation.PSCustomObject*') { $objType = 'dynamic' }
|            else { $objType = 'dynamic' }
|            [void]$seen.Add($c.Name)
|            [void]$table.Add((& $mk $c.Name $objType -Desc))
|            [void]$dcr.Add((& $mk $c.Name $objType))
|        }
|    }
|    foreach ($n in $nullOnly) {
|        if ($seen.Contains($n)) { continue }
|        [void]$seen.Add($n)
|        [void]$table.Add((& $mk $n 'dynamic' -Desc))
|        [void]$dcr.Add((& $mk $n 'dynamic'))
|    }
|    if ($ReturnType -eq 'Table') { return $table.ToArray() }
|    if ($ReturnType -eq 'DCR' -or $As -eq 'Array') { return $dcr.ToArray() }
|}
|
|function Format-SILogRowsToSchemaRest {
|    <# Twin of Build-DataArrayToAlignWithSchema (1.7.x): every row gets every schema column (missing = $null), in
|       schema order; a property the schema does not list (a literal TimeGenerated) is kept, after them.
|       #639: IN PLACE, never a padded copy of the whole post. A PSCustomObject row is aligned on itself (its properties
|       re-ordered, the missing ones added as $null) -- the same row, the same JSON as the copy made before; a row of another
|       kind (a hashtable, a compact .NET row) is replaced in the array by its aligned copy, one row at a time. The post
|       then serialises a batch at a time (Send-SILogDataRest), so nothing of the post is ever held twice. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    $schema = Get-SILogSchemaRest -Data $Data -As Array
|    if (@($Data).Count -eq 0) { return $Data }
|    $names = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($c in $schema) { [void]$names.Add([string]$c.name) }
|    $nm = $names.ToArray()
|    for ($i = 0; $i -lt $Data.Count; $i++) { $Data[$i] = Format-SILogRowToNamesInPlace -Row $Data[$i] -Names $nm }
|    return $Data
|}
|
|function Format-SILogRowToNamesInPlace {
|    <# ONE row aligned to -Names (missing = $null, in that order, the other properties after them) -- the row itself when
|       it is a PSCustomObject (its properties re-ordered in place; nothing done when it already is aligned), else its
|       aligned copy (Format-SILogRowsToNames). The JSON of the result equals the JSON of Format-SILogRowsToNames. #>
|    param($Row, [Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    if ($null -eq $Row) { return $Row }
|    if ($Row.PSObject.BaseObject -isnot [System.Management.Automation.PSCustomObject]) {
|        return @(Format-SILogRowsToNames -Data @($Row) -Names $Names)[0]
|    }
|    $props = $Row.PSObject.Properties
|    # already aligned: the names first, in order, every one present -- nothing to do
|    $all = @($props)
|    $aligned = ($all.Count -ge $Names.Count)
|    if ($aligned) { for ($k = 0; $k -lt $Names.Count; $k++) { if ($all[$k].Name -cne $Names[$k] -or $all[$k] -isnot [System.Management.Automation.PSNoteProperty]) { $aligned = $false; break } } }
|    if ($aligned) { return $Row }
|    foreach ($p in $all) { if ($p -isnot [System.Management.Automation.PSNoteProperty]) { return @(Format-SILogRowsToNames -Data @($Row) -Names $Names)[0] } }
|    $set = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($n in $Names) { [void]$set.Add($n) }
|    # the values, then the properties rebuilt on the same object: the names in order, then the others as they were
|    $vals = @{}
|    $rest = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($p in $all) {
|        if ($set.Contains($p.Name)) { if (-not $vals.ContainsKey($p.Name)) { $vals[$p.Name] = $p } }
|        else { $rest.Add($p) }
|    }
|    foreach ($p in $all) { $props.Remove($p.Name) }
|    foreach ($n in $Names) {
|        $v = $null; if ($vals.ContainsKey($n)) { $v = $vals[$n].Value }
|        $props.Add([System.Management.Automation.PSNoteProperty]::new($n, $v))
|    }
|    foreach ($p in $rest) { $props.Add([System.Management.Automation.PSNoteProperty]::new($p.Name, $p.Value)) }
|    return $Row
|}
|
|function Format-SILogRowsToNames {
|    <# PURE. Format-SILogRowsToSchemaRest's second half: every row gets every column of -Names (missing = $null), in that
|       order; a property not in -Names is kept, after them. Each row on its own -- the names are the whole set's schema, read
|       before (Risk Analysis prepares the rows of one chunk on several cores with it, #744). #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][Array]$Data, [Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($row in $Data) {
|        $props = $row.PSObject.Properties
|        $a = [ordered]@{}
|        foreach ($n in $Names) { $p = $props[$n]; if ($null -ne $p) { $a[$n] = $p.Value } else { $a[$n] = $null } }
|        foreach ($p in $props) { if (-not $a.Contains($p.Name)) { $a[$p.Name] = $p.Value } }
|        [void]$out.Add([pscustomobject]$a)
|    }
|    return $out.ToArray()
|}
|
|# =====================================================================================================================
|#  REST: table + DCR create / update -- ADDITIVE only
|# =====================================================================================================================
|
|function Get-SILogStreamName {
|    <# 'Custom-<table>_CL', cut to 52 characters (the stream name limit) -- the module's rule. #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = 'Custom-' + $TableName + '_CL'
|    if ($s.Length -gt 52) { $s = $s.Substring(0, 52) }
|    return $s
|}
|
|function Get-SILogTableRest {
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [hashtable]$Auth, [switch]$NoCache)
|    return (Invoke-SILogArm -Path ($WorkspaceResourceId + '/tables/' + $TableName + '_CL') -ApiVersion (Get-SILogArmApiVersion Table) -Auth $Auth -AllowNotFound -NoCache:$NoCache)
|}
|
|function Resolve-SILogDcrForTable {
|    <# The rule this install posts through: the one recorded this run when it was created/updated, else by name in the
|       configured scope (Find-SILogResourceByName). #>
|    param([Parameter(Mandatory)][string]$DcrName, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth)
|    $ids = (Get-SILogIngestRunCache).DcrIds
|    $key = $DcrName.ToLowerInvariant()   # the rule created / updated / found THIS run, wherever the caller put it
|    if ($ids.ContainsKey($key)) {
|        $hit = Invoke-SILogArm -Path $ids[$key] -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $Auth -AllowNotFound
|        if ($hit) { return $hit }
|    }
|    return (Find-SILogResourceByName -Kind Dcr -Name $DcrName -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -Auth $Auth)
|}
|
|function Test-SILogTableDcrStatusRest {
|    <# Twin of Get-AzLogAnalyticsTableAzDataCollectionRuleStatus: $true when the table or the rule must be created or
|       given columns. The rule is looked up in the configured scope, not by name across the tenant. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string]$DcrName,
|          [Parameter(Mandatory)][array]$SchemaSourceObject, [string]$DcrResourceGroup,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    $needs = $false
|    $t = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $cols = @(); $std = @()
|    if (-not $t) { $needs = $true }
|    else {
|        $cols = @($t.properties.schema.columns); $std = @($t.properties.schema.standardColumns)
|        foreach ($e in $SchemaSourceObject) {
|            if (-not ($cols | Where-Object { $_.name -eq $e.name }) -and -not ($std | Where-Object { $_.name -eq $e.name })) { $needs = $true }
|        }
|    }
|    $dcr = Resolve-SILogDcrForTable -DcrName $DcrName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DcrRg -Auth $auth
|    if (-not $dcr) { return $true }
|    (Get-SILogIngestRunCache).DcrIds[$DcrName.ToLowerInvariant()] = [string]$dcr.id   # the post uses THIS rule
|    $stream = Get-SILogStreamName -TableName $TableName
|    $dcrCols = @()
|    if ($dcr.properties.streamDeclarations -and $dcr.properties.streamDeclarations.PSObject.Properties[$stream]) { $dcrCols = @($dcr.properties.streamDeclarations.$stream.columns) }
|    $tableCols = @($cols | Where-Object { $_.name -ne 'TimeGenerated' })
|    if ($dcrCols.Count -lt $tableCols.Count) { return $true }
|    foreach ($c in $tableCols) { if (-not ($dcrCols | Where-Object { $_.name -eq $c.name })) { $needs = $true } }
|    return $needs
|}
|
|function Set-SILogTableRest {
|    <#
|        Twin of CreateUpdate-AzLogAnalyticsCustomLogTableDcr, ADDITIVE ONLY:
|          no table   -> PUT it with the schema of the data (TimeGenerated + every column)
|          table      -> the columns it does not have yet are added (PATCH: retention and plan are left as they are); an
|                        existing column is never changed or removed, whatever type the data now suggests
|        A refused write FAILS with Azure's answer. The module's fallback -- DELETE the table and re-create it -- is not
|        copied: it discards data.
|        -SchemaSourceObject: the Table-format schema (Get-SILogSchemaRest -ReturnType Table / Get-ObjectSchemaAsHash).
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][array]$SchemaSourceObject, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId,
|          [string]$SchemaMode = 'Merge',
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $table = $TableName + '_CL'
|    if ($table.Length -gt 45) { Write-Error ("ERROR - Reduce length of tablename, as it has a maximum of 45 characters (current length: {0})" -f $table.Length) }
|    $path = $AzLogWorkspaceResourceId + '/tables/' + $table
|    $cur = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $toCol = { param($c) [ordered]@{ name = [string]$c.name; type = [string]$c.type; description = '' } }
|    if (-not $cur) {
|        $columns = @($SchemaSourceObject | ForEach-Object { & $toCol $_ })
|        $null = Invoke-SILogArm -Method PUT -Path $path -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth -Body @{ properties = @{ schema = @{ name = $table; columns = $columns } } }
|        Write-Output ("table {0}: created with {1} column(s)" -f $table, $columns.Count)
|        return
|    }
|    $std = @($cur.properties.schema.standardColumns | ForEach-Object { [string]$_.name })
|    $merged = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($c in @($cur.properties.schema.columns)) { if ($c -and ([string]$c.name -notin $std)) { [void]$merged.Add((& $toCol $c)) } }
|    $added = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($s in $SchemaSourceObject) {
|        if ([string]$s.name -in $std) { continue }
|        if (@($merged | Where-Object { $_.name -eq [string]$s.name }).Count) { continue }
|        [void]$merged.Add((& $toCol $s)); [void]$added.Add([string]$s.name)
|    }
|    if ($added.Count -eq 0) { Write-Output ("table {0}: has every column" -f $table); return }
|    $null = Invoke-SILogArm -Method PATCH -Path $path -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth -Body @{ properties = @{ schema = @{ name = $table; columns = @($merged.ToArray()) } } }
|    Write-Output ("table {0}: {1} column(s) added ({2})" -f $table, $added.Count, ($added -join ', '))
|}
|
|function Resolve-SILogEndpointForNewRule {
|    <# This install's endpoint, for a NEW rule: by name in SI_DceResourceGroup (else the rules' group) of the
|       subscription; one of that name elsewhere in the subscription is unambiguous; several refuse. #>
|    param([Parameter(Mandatory)][string]$DceName, $Scope, [hashtable]$Auth)
|    $dce = Find-SILogResourceByName -Kind Dce -Name $DceName -SubscriptionId $Scope.Subscription -ResourceGroup $Scope.DceRg -Auth $Auth -AnyResourceGroupWhenMissing
|    if (-not $dce) {
|        throw ("Data collection endpoint '{0}' was not found in resource group '{1}' of subscription '{2}', so nothing was created or posted." -f $DceName, $Scope.DceRg, $Scope.Subscription)
|    }
|    return $dce
|}
|
|function Set-SILogDcrRest {
|    <#
|        Twin of CreateUpdate-AzDataCollectionRuleLogIngestCustomLog, ADDITIVE ONLY:
|          no rule -> PUT one in the configured subscription + resource group, bound to THIS install's endpoint, with the
|                     stream declaration (the data's columns), the workspace destination and the default transform
|          rule    -> the columns the table has and the stream does not are ADDED to the stream declaration; everything
|                     else the rule carries (its endpoint, transform, destinations, other streams) is kept as it is. The
|                     module rebuilt the whole rule instead, re-binding it to the endpoint it found by name (#198).
|        A new rule waits 15 seconds for Azure to settle, as the module did.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][array]$SchemaSourceObject, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [string]$DceName,
|          [Parameter(Mandatory)][string]$DcrResourceGroup, [Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][string]$TableName,
|          [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel = $false, [AllowEmptyString()][string]$LogIngestServicePricipleObjectId, [string]$SchemaMode = 'Merge',
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    $stream = Get-SILogStreamName -TableName $TableName
|    $wsName = ($AzLogWorkspaceResourceId -split '/')[-1]
|    $dcrPath = "/subscriptions/$($scope.Subscription)/resourceGroups/$DcrResourceGroup/providers/Microsoft.Insights/dataCollectionRules/$DcrName"
|    $ids = (Get-SILogIngestRunCache).DcrIds
|    $key = $DcrName.ToLowerInvariant()
|    $dcr = Invoke-SILogArm -Path $dcrPath -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -AllowNotFound -NoCache
|    $toCol = { param($c) [ordered]@{ name = [string]$c.name; type = [string]$c.type } }
|
|    if (-not $dcr) {
|        $dce = Resolve-SILogEndpointForNewRule -DceName $DceName -Scope $scope -Auth $auth
|        # #294: a new rule for a table that EXISTS declares the table's columns with the TABLE's types (then any column of
|        # the data the table does not have yet). Declared from the data instead, a type that differs from the table's
|        # (a column the data reads as an object, the table holds as text) makes Azure refuse the rule.
|        $tNew = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|        $cols = @(Get-SILogNewRuleColumns -Table $tNew -SchemaSourceObject $SchemaSourceObject)
|        $body = [ordered]@{
|            location   = [string]$dce.location
|            properties = [ordered]@{
|                dataCollectionEndpointId = [string]$dce.id
|                streamDeclarations       = @{ $stream = @{ columns = $cols } }
|                destinations             = @{ logAnalytics = @(@{ workspaceResourceId = $AzLogWorkspaceResourceId; name = $wsName }) }
|                dataFlows                = @(@{ streams = @($stream); destinations = @($wsName); transformKql = 'source | extend TimeGenerated = now()'; outputStream = $stream })
|            }
|        }
|        $created = Invoke-SILogArm -Method PUT -Path $dcrPath -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -Body $body
|        $ids[$key] = $dcrPath
|        Write-Output ("data collection rule {0}: created on endpoint {1} with {2} column(s)" -f $DcrName, $dce.id, $cols.Count)
|        if ($AzDcrSetLogIngestApiAppPermissionsDcrLevel -and $LogIngestServicePricipleObjectId) {
|            $roleDef = "/subscriptions/$($scope.Subscription)/providers/Microsoft.Authorization/roleDefinitions/3913510d-42f4-4e42-8a64-420c390055eb"
|            try {
|                $null = Invoke-SILogArm -Method PUT -Path ($dcrPath + '/providers/Microsoft.Authorization/roleAssignments/' + [guid]::NewGuid().ToString()) -ApiVersion (Get-SILogArmApiVersion Role) -Auth $auth `
|                    -Body @{ properties = @{ roleDefinitionId = $roleDef; principalId = $LogIngestServicePricipleObjectId; principalType = 'ServicePrincipal' } }
|            } catch { Write-Warning ("Monitoring Metrics Publisher on {0} was not granted: {1}" -f $DcrName, $_.Exception.Message) }
|        }
|        Start-Sleep -Seconds 15
|        return
|    }
|
|    $ids[$key] = [string]$dcr.id
|    # the columns the stream must carry: the table's (after Set-SILogTableRest), plus Computer/RawData when they are
|    # standard columns of a table migrated from v1 -- the module's rule
|    $t = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $want = New-Object 'System.Collections.Generic.List[object]'
|    if ($t) {
|        foreach ($c in @($t.properties.schema.columns)) { if ($c -and $c.name -ne 'TimeGenerated') { [void]$want.Add((& $toCol $c)) } }
|        foreach ($n in 'Computer', 'RawData') {
|            if (-not @($want | Where-Object { $_.name -eq $n }).Count -and @($t.properties.schema.standardColumns | Where-Object { $_.name -eq $n }).Count) { [void]$want.Add([ordered]@{ name = $n; type = 'string' }) }
|        }
|    } else {
|        foreach ($c in $SchemaSourceObject) { if ($c.name -ne 'TimeGenerated') { [void]$want.Add((& $toCol $c)) } }
|    }
|    $p = $dcr.properties
|    if (-not $p.streamDeclarations) { $p | Add-Member -NotePropertyName streamDeclarations -NotePropertyValue ([pscustomobject]@{}) -Force }
|    $hasStream = [bool]$p.streamDeclarations.PSObject.Properties[$stream]
|    $have = if ($hasStream) { @($p.streamDeclarations.$stream.columns) } else { @() }
|    $merged = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($c in $have) { if ($c) { [void]$merged.Add((& $toCol $c)) } }
|    $added = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($c in $want) { if (-not @($merged | Where-Object { $_.name -eq $c.name }).Count) { [void]$merged.Add($c); [void]$added.Add([string]$c.name) } }
|    if ($added.Count -eq 0) { Write-Output ("data collection rule {0}: has every column" -f $DcrName); return }
|
|    if ($hasStream) { $p.streamDeclarations.$stream.columns = @($merged.ToArray()) }
|    else {
|        $p.streamDeclarations | Add-Member -NotePropertyName $stream -NotePropertyValue ([pscustomobject]@{ columns = @($merged.ToArray()) })
|        $flows = @($p.dataFlows)
|        if (-not @($flows | Where-Object { @($_.streams) -contains $stream }).Count) {
|            $dest = @($p.destinations.logAnalytics)[0]
|            $p.dataFlows = @($flows) + @([pscustomobject]@{ streams = @($stream); destinations = @([string]$dest.name); transformKql = 'source | extend TimeGenerated = now()'; outputStream = $stream })
|        }
|    }
|    $props = [ordered]@{}
|    foreach ($q in $p.PSObject.Properties) { if ($q.Name -notin 'immutableId', 'provisioningState', 'endpoints', 'metadata') { $props[$q.Name] = $q.Value } }
|    $body = [ordered]@{ location = [string]$dcr.location; properties = $props }
|    if ($dcr.PSObject.Properties['kind'] -and $dcr.kind) { $body['kind'] = $dcr.kind }
|    if ($dcr.PSObject.Properties['tags'] -and $dcr.tags) { $body['tags'] = $dcr.tags }
|    $null = Invoke-SILogArm -Method PUT -Path ([string]$dcr.id) -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -Body $body
|    Write-Output ("data collection rule {0}: {1} column(s) added to {2} ({3})" -f $DcrName, $added.Count, $stream, ($added -join ', '))
|}
|
|function Update-SILogTableSchemaRest {
|    <#
|        Twin of CheckCreateUpdate-TableDcr-Structure: the table and the rule carry every column of the data (the WHOLE
|        set decides the schema). Same arguments as the module. Additive only (Set-SILogTableRest / Set-SILogDcrRest).
|        A table name with '_' first, '-', ':', '.' or a space is refused as the module refuses it (nothing is done).
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [Parameter(Mandatory)][string]$TableName,
|          [Parameter(Mandatory)][string]$DcrName, [string]$DcrResourceGroup, [string]$DceName,
|          [AllowEmptyString()][AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel = $false,
|          [boolean]$AzLogDcrTableCreateFromAnyMachine, [string]$SchemaMode = 'Merge', [boolean]$EnableUploadViaLogHub = $false,
|          [AllowEmptyCollection()][array]$AzLogDcrTableCreateFromReferenceMachine,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    if ($TableName -like '_*' -or $TableName -like '*-*' -or $TableName -like '*:*' -or $TableName -like '*.*' -or $TableName -like '* *') {
|        Write-Verbose ("ISSUE - Table name [ {0} ] is not a valid Log Analytics table name" -f $TableName)
|        return
|    }
|    if ($EnableUploadViaLogHub) { return }
|    if (-not ($AzLogDcrTableCreateFromAnyMachine -or ($env:COMPUTERNAME -and $env:COMPUTERNAME -in @($AzLogDcrTableCreateFromReferenceMachine)))) { return }
|    if (-not $DcrResourceGroup) { $DcrResourceGroup = (Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId).DcrRg }
|    $authArgs = @{}
|    foreach ($k in 'AzAppId', 'AzAppSecret', 'AzAppCertificateThumbprint', 'AzAppCertificateStoreLocation', 'UseManagedIdentity', 'ManagedIdentityClientId', 'TenantId') {
|        if ($PSBoundParameters.ContainsKey($k)) { $authArgs[$k] = $PSBoundParameters[$k] }
|    }
|    $schema = Get-SILogSchemaRest -Data $Data -As Array
|    $needs = Test-SILogTableDcrStatusRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -DcrName $DcrName -SchemaSourceObject $schema -DcrResourceGroup $DcrResourceGroup @authArgs
|    if (-not $needs) { Write-Output ("table {0}_CL and rule {1}: every column is declared" -f $TableName, $DcrName); return }
|    Set-SILogTableRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -SchemaSourceObject (Get-SILogSchemaRest -Data $Data -As Hash -ReturnType Table) -SchemaMode $SchemaMode @authArgs
|    Set-SILogDcrRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -SchemaSourceObject (Get-SILogSchemaRest -Data $Data -As Hash -ReturnType DCR) `
|        -DceName $DceName -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -SchemaMode $SchemaMode `
|        -LogIngestServicePricipleObjectId $LogIngestServicePricipleObjectId -AzDcrSetLogIngestApiAppPermissionsDcrLevel $AzDcrSetLogIngestApiAppPermissionsDcrLevel @authArgs
|}
|
|# =====================================================================================================================
|#  REST: upload
|# =====================================================================================================================
|
|function ConvertTo-SILogGzip {
|    param([Parameter(Mandatory)][byte[]]$Bytes)
|    $ms = New-Object System.IO.MemoryStream
|    try {
|        $gz = New-Object System.IO.Compression.GZipStream($ms, [System.IO.Compression.CompressionMode]::Compress, $true)
|        try { $gz.Write($Bytes, 0, $Bytes.Length) } finally { $gz.Dispose() }
|        return , $ms.ToArray()
|    } finally { $ms.Dispose() }
|}
|
|function Send-SILogIngestBatch {
|    <# Posts rows [List of row JSON bytes] as one JSON array. Measured: when the payload (compressed when -State says
|       so) exceeds the limit, the batch is split in two and each half measured again. #>
|    param([Parameter(Mandatory)]$Rows, [Parameter(Mandatory)][hashtable]$State)
|    $raw = New-Object System.IO.MemoryStream
|    try {
|        $raw.WriteByte(0x5B)
|        for ($i = 0; $i -lt $Rows.Count; $i++) { if ($i -gt 0) { $raw.WriteByte(0x2C) }; $b = $Rows[$i]; $raw.Write($b, 0, $b.Length) }
|        $raw.WriteByte(0x5D)
|        $rawBytes = $raw.ToArray()
|    } finally { $raw.Dispose() }
|    $payload = if ($State.Compress) { ConvertTo-SILogGzip -Bytes $rawBytes } else { $rawBytes }
|    if ($payload.Length -gt $State.MaxBytes) {
|        if ($Rows.Count -eq 1) { throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f $payload.Length, $State.MaxBytes) }
|        $half = [int][Math]::Floor($Rows.Count / 2)
|        $a = New-Object 'System.Collections.Generic.List[byte[]]'; $z = New-Object 'System.Collections.Generic.List[byte[]]'
|        for ($i = 0; $i -lt $Rows.Count; $i++) { if ($i -lt $half) { [void]$a.Add($Rows[$i]) } else { [void]$z.Add($Rows[$i]) } }
|        Send-SILogIngestBatch -Rows $a -State $State
|        Send-SILogIngestBatch -Rows $z -State $State
|        return
|    }
|    if ($State.Compress -and $rawBytes.Length -gt 0) { $State.Ratio = [Math]::Max(0.01, $payload.Length / $rawBytes.Length) }
|    $from = $State.Posted + 1; $to = $State.Posted + $Rows.Count
|    Write-Host ''
|    Write-Host ("  Posting data to LogAnalytics table [ {0}_CL ]" -f $State.Table)
|    Write-Host ("    Rows       : {0}..{1} / {2}" -f $from, $to, $State.Total)
|    Write-Host ("    {0} | {1}" -f $(if ($State.Compress) { 'Compression=ON' } else { 'Compression=OFF' }), $State.AuthText)
|    Write-Host ''
|    $h = @{}
|    if ($State.Compress) { $h['Content-Encoding'] = 'gzip' }
|    $null = Invoke-SILogIngestRequest -Method POST -Uri $State.Uri -Body ([byte[]]$payload) -ContentType 'application/json' -Headers $h `
|        -Resource 'https://monitor.azure.com/' -Auth $State.Auth -What 'Log Ingestion API request'
|    $State.Posted += $Rows.Count
|    $State.Bytes += [long]$rawBytes.Length
|    $State.Batches++
|    Write-Host '  SUCCESS - data uploaded to LogAnalytics' -ForegroundColor Green
|}
|
|# =====================================================================================================================
|#  REST: the PARALLEL SENDER (#738) -- for a caller that posts one large result in many calls (Risk Analysis)
|#
|#  A large install, 2026-10-17: 1,138,554 Risk Analysis rows reached Log Analytics at ~2,200 rows a minute (~8.5 hours). Every post
|#  was made, and waited for, in line with the work that builds the rows: the page read, the preparation, the JSON, then one
|#  POST at a time, each ~half full (the batch split in two whenever the compressed size went over the limit).
|#  A sender changes only HOW the rows travel, never WHICH rows or their JSON (the rows are serialised exactly as before, by
|#  Send-SILogDataRest, in the order given):
|#    * each POST is filled close to the API's limit: the rows are compressed, the compressed size MEASURED, and a batch that
|#      comes out over the limit gives back its last rows to the next batch (no half batches); the compression ratio adapts
|#      from every measurement; a 413 from the service lowers the limit and the batch is split and sent again;
|#    * up to -Degree POSTs are in flight at once (a small fixed number, 4), each on its own worker; a 429 / 408 / 5xx / no
|#      answer is retried by its worker after the service's Retry-After, and a 429 holds EVERY worker until then;
|#    * the endpoint, the rule and the token are resolved once per sender (the token from the run's cache, refreshed on 401);
|#    * the rows confirmed by the service (2xx) are COUNTED; Complete-SILogIngestSender throws when they are fewer than the
|#      rows handed over -- the same verdict as before. A failed post stops the next hand-over at once (the error is the
|#      same text as a failed synchronous post).
|#  Started by the caller (Start-SILogIngestSender -TableName), then every Send-SILogData for that table goes through it;
|#  any other table, and every caller that never starts one, posts synchronously exactly as before.
|# =====================================================================================================================
|
|function Get-SILogIngestSenderWorkerScript {
|    <# The worker: one POST with the retry rule (working rule 4), holding while the service asked every worker to wait. #>
|    @'
|param([string]$Uri, [byte[]]$Body, [hashtable]$Headers, [int]$MaxAttempts, $Gate)
|$notes = New-Object 'System.Collections.Generic.List[string]'
|for ($attempt = 1; ; $attempt++) {
|    while ($true) {
|        $until = [long]$Gate['PauseUntil']; $now = [datetime]::UtcNow.Ticks
|        if ($until -le $now) { break }
|        Start-Sleep -Milliseconds ([int][Math]::Min(60000, [Math]::Ceiling(($until - $now) / 10000.0)) + 1)
|    }
|    $r = Invoke-SILogIngestHttp -Method POST -Uri $Uri -Headers $Headers -Body $Body -ContentType 'application/json'
|    $code = [int]$r.StatusCode
|    if ($code -ge 200 -and $code -lt 300) { return @{ Code = $code; Attempts = $attempt; Content = ''; Notes = $notes.ToArray() } }
|    $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|    if (-not $transient -or $attempt -ge $MaxAttempts) { return @{ Code = $code; Attempts = $attempt; Content = [string]$r.Content; Notes = $notes.ToArray() } }
|    $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|    if ($code -eq 429) {
|        [System.Threading.Monitor]::Enter($Gate.SyncRoot)
|        try { $t = [datetime]::UtcNow.AddSeconds($wait).Ticks; if ($t -gt [long]$Gate['PauseUntil']) { $Gate['PauseUntil'] = $t } } finally { [System.Threading.Monitor]::Exit($Gate.SyncRoot) }
|    }
|    if ($code -eq 0 -or $wait -ge 30) {
|        $notes.Add((" [INFO] Log Ingestion API request: {0} -- trying again in {1} second(s) (attempt {2} of {3})" -f $(if ($code -eq 0) { 'no answer from Azure' } else { 'Azure answered HTTP {0}' -f $code }), $wait, $attempt, $MaxAttempts))
|    }
|    [System.Threading.Monitor]::Enter($Gate.SyncRoot)
|    try { $Gate['Retries'] = 1 + [int]$Gate['Retries'] } finally { [System.Threading.Monitor]::Exit($Gate.SyncRoot) }
|    Start-Sleep -Seconds $wait
|}
|'@
|}
|
|function Get-SILogIngestSender {
|    <# The sender started for -TableName in this run ($null when none). #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $c = Get-SILogIngestRunCache
|    if (-not ($c.Senders -is [hashtable])) { return $null }
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if ($c.Senders.ContainsKey($k)) { return $c.Senders[$k] }
|    $null
|}
|
|function Get-SILogIngestPostDegree {
|    <# PURE over the setting. POSTs in flight at once: 4 (a small fixed number). SI_LogIngest_ParallelPosts (global) or the
|       environment variable SI_LOGINGEST_PARALLELPOSTS: 1 / 0 / off = one at a time; a number = that many, at most 8. #>
|    param($Setting = $(Get-Variable -Scope Global -Name SI_LogIngest_ParallelPosts -ValueOnly -ErrorAction Ignore), [AllowNull()][AllowEmptyString()][string]$EnvValue = $env:SI_LOGINGEST_PARALLELPOSTS)
|    $s = if ($null -ne $Setting -and ([string]$Setting).Trim() -ne '') { ([string]$Setting).Trim() } elseif ($EnvValue) { $EnvValue.Trim() } else { '' }
|    if ($s -match '^(?i)(off|false|no|disabled?)$') { return 1 }
|    $n = 0
|    if ($s -ne '' -and [int]::TryParse($s, [ref]$n)) { if ($n -le 1) { return 1 }; return [Math]::Min(8, $n) }
|    4
|}
|
|function Start-SILogIngestSender {
|    <# Starts the sender for -TableName (see the block above). -Degree: POSTs in flight at once (Get-SILogIngestPostDegree).
|       -MaxPayloadBytes: the API's limit per call; each POST is filled to -Fill of it (measured after compression). #>
|    param([Parameter(Mandatory)][string]$TableName, [int]$Degree = 0, [long]$MaxPayloadBytes = 1MB, [double]$Fill = 0.95, [int]$MaxAttempts = 6)
|    if ($Degree -le 0) { $Degree = Get-SILogIngestPostDegree }
|    $c = Get-SILogIngestRunCache
|    if (-not ($c.Senders -is [hashtable])) { $c.Senders = @{} }
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if ($c.Senders.ContainsKey($k)) { Stop-SILogIngestSender -TableName $TableName }
|    $s = @{
|        Table = ($TableName -replace '_CL$', ''); Degree = $Degree; MaxBytes = [long]$MaxPayloadBytes; Fill = $Fill; MaxAttempts = $MaxAttempts
|        Uri = $null; Auth = $null; AuthText = ''; Compress = $true; Ratio = 1.0
|        Pending = (New-Object 'System.Collections.Generic.List[byte[]]'); PendingBytes = 2L
|        InFlight = (New-Object 'System.Collections.Generic.List[object]')
|        Accepted = 0L; Dispatched = 0L; Confirmed = 0L; Bytes = 0L; SentBytes = 0L; Posts = 0; Split413 = 0; MaxSent = 0L
|        Failed = $null; Pool = $null; Gate = [hashtable]::Synchronized(@{ PauseUntil = 0L; Retries = 0 }); Script = (Get-SILogIngestSenderWorkerScript)
|    }
|    if ($Degree -gt 1) {
|        # the worker's environment: the HTTP seam and the retry delay AS THEY ARE in this run (a test's fake service
|        # included), and $SILogSeam (the test seam's shared state, $null in a real run). Never a script block of this
|        # runspace: a worker runs only text it was given.
|        $iss = [System.Management.Automation.Runspaces.InitialSessionState]::CreateDefault2()
|        foreach ($fn in 'Invoke-SILogIngestHttp', 'Get-SILogIngestRetryDelay') {
|            $def = (Get-Command -Name $fn -CommandType Function -ErrorAction Stop).Definition
|            $iss.Commands.Add((New-Object System.Management.Automation.Runspaces.SessionStateFunctionEntry($fn, $def)))
|        }
|        $seam = Get-Variable -Scope Global -Name SILogSeam -ValueOnly -ErrorAction Ignore
|        $iss.Variables.Add((New-Object System.Management.Automation.Runspaces.SessionStateVariableEntry('SILogSeam', $seam, '')))
|        $pool = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspacePool(1, $Degree, $iss, $Host)
|        $pool.Open()
|        $s.Pool = $pool
|    }
|    $c.Senders[$k] = $s
|    $s
|}
|
|function Send-SILogIngestSenderBatch {
|    <# Hands one payload to a worker (or posts it here when the sender has no workers), waiting first while -Degree are in flight. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][byte[]]$Payload, [Parameter(Mandatory)][hashtable]$Batch)
|    while ($Sender.InFlight.Count -ge [Math]::Max(1, $Sender.Degree)) { Receive-SILogIngestSenderResults -Sender $Sender -WaitOne }
|    # once a post has failed, nothing more goes out (the run fails; the rows not posted are counted as not confirmed)
|    if ($Sender.Failed) { return }
|    $token = Get-SILogIngestToken -Resource 'https://monitor.azure.com/' -Auth $Sender.Auth -ForceRefresh:([bool]$Batch.Refresh)
|    $h = @{ 'Authorization' = ('Bearer ' + $token) }
|    if ($Sender.Compress) { $h['Content-Encoding'] = 'gzip' }
|    $Batch.Payload = $Payload
|    $Sender.Posts++
|    if ($null -eq $Sender.Pool) {
|        $res = & ([scriptblock]::Create($Sender.Script)) $Sender.Uri $Payload $h $Sender.MaxAttempts $Sender.Gate
|        Complete-SILogIngestSenderBatch -Sender $Sender -Batch $Batch -Result $res
|        return
|    }
|    $ps = [powershell]::Create()
|    $ps.RunspacePool = $Sender.Pool
|    [void]$ps.AddScript($Sender.Script).AddArgument($Sender.Uri).AddArgument($Payload).AddArgument($h).AddArgument($Sender.MaxAttempts).AddArgument($Sender.Gate)
|    $Batch.PS = $ps
|    $Batch.Handle = $ps.BeginInvoke()
|    [void]$Sender.InFlight.Add($Batch)
|}
|
|function Complete-SILogIngestSenderBatch {
|    <# One post's answer: 2xx = its rows confirmed (said as before); 401 = sent once more with a fresh token; 413 = the limit
|       is lowered and the batch split and sent again; anything else = the sender has FAILED (same text as a failed post). #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][hashtable]$Batch, $Result)
|    $r = $Result
|    if ($r -is [System.Collections.IEnumerable] -and -not ($r -is [hashtable])) { $r = @($r | Where-Object { $_ -is [hashtable] }) | Select-Object -Last 1 }
|    if (-not ($r -is [hashtable])) { $r = @{ Code = 0; Content = 'the post''s worker returned no answer'; Notes = @() } }
|    foreach ($n in @($r.Notes)) { if ($n) { Write-Host $n } }
|    $code = [int]$r.Code
|    if ($code -ge 200 -and $code -lt 300) {
|        $Sender.Confirmed += $Batch.Rows.Count
|        $Sender.Bytes += [long]$Batch.Raw
|        $Sender.SentBytes += [long]$Batch.Payload.Length
|        if ($Batch.Payload.Length -gt $Sender.MaxSent) { $Sender.MaxSent = [long]$Batch.Payload.Length }
|        Write-Host ''
|        Write-Host ("  Posting data to LogAnalytics table [ {0}_CL ]" -f $Sender.Table)
|        Write-Host ("    Rows       : {0}..{1} / {2}" -f $Batch.From, ($Batch.From + $Batch.Rows.Count - 1), $Sender.Accepted)
|        Write-Host ("    {0} | {1} | {2:n0} bytes" -f $(if ($Sender.Compress) { 'Compression=ON' } else { 'Compression=OFF' }), $Sender.AuthText, $Batch.Payload.Length)
|        Write-Host ''
|        Write-Host '  SUCCESS - data uploaded to LogAnalytics' -ForegroundColor Green
|        return
|    }
|    if ($code -eq 401 -and -not $Batch.Refresh -and -not $Sender.Failed) {
|        $Batch.Refresh = $true
|        Send-SILogIngestSenderBatch -Sender $Sender -Payload $Batch.Payload -Batch $Batch
|        return
|    }
|    if ($code -eq 413 -and $Batch.Rows.Count -gt 1 -and -not $Sender.Failed) {
|        # the service's own limit is lower than ours: lower it under this payload and send the rows again in two
|        $Sender.MaxBytes = [long][Math]::Max(65536, [Math]::Floor($Batch.Payload.Length * 0.9))
|        $Sender.Split413++
|        $half = [int][Math]::Floor($Batch.Rows.Count / 2)
|        $a = New-Object 'System.Collections.Generic.List[byte[]]'; $z = New-Object 'System.Collections.Generic.List[byte[]]'
|        for ($i = 0; $i -lt $Batch.Rows.Count; $i++) { if ($i -lt $half) { [void]$a.Add($Batch.Rows[$i]) } else { [void]$z.Add($Batch.Rows[$i]) } }
|        $Sender.Dispatched -= $Batch.Rows.Count
|        Send-SILogIngestSenderRows -Sender $Sender -Rows $a -From $Batch.From
|        Send-SILogIngestSenderRows -Sender $Sender -Rows $z -From ($Batch.From + $half)
|        return
|    }
|    if (-not $Sender.Failed) { $Sender.Failed = ("Log Ingestion API request failed. HTTP Status: {0} Response: {1}" -f $code, $r.Content) }
|}
|
|function Receive-SILogIngestSenderResults {
|    <# Collects the answers of the posts that finished; -WaitOne waits for at least one (when any is in flight); -All for all. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [switch]$WaitOne, [switch]$All)
|    while ($Sender.InFlight.Count -gt 0) {
|        $done = @($Sender.InFlight | Where-Object { $_.Handle.IsCompleted })
|        if ($done.Count -eq 0) {
|            if (-not $WaitOne -and -not $All) { return }
|            $handles = [System.Threading.WaitHandle[]]@($Sender.InFlight | ForEach-Object { $_.Handle.AsyncWaitHandle } | Select-Object -First 64)
|            [void][System.Threading.WaitHandle]::WaitAny($handles, 1000)
|            continue
|        }
|        # out of the list first: answering one post can send another (401, 413) and wait for the workers again
|        foreach ($b in $done) { [void]$Sender.InFlight.Remove($b) }
|        # each answer on its own: one that throws (a token fetch for a 401 resend, a record too large in a 413 split) is the
|        # sender's FIRST error -- every other finished post is still counted and its worker disposed
|        foreach ($b in $done) {
|            $res = $null
|            try { $res = @($b.PS.EndInvoke($b.Handle)) | ForEach-Object { $_.psobject.BaseObject } | Where-Object { $_ -is [hashtable] } | Select-Object -Last 1 }
|            catch { $res = @{ Code = 0; Content = $_.Exception.Message; Notes = @() } }
|            finally { try { $b.PS.Dispose() } catch { }; $b.PS = $null; $b.Handle = $null }
|            try { Complete-SILogIngestSenderBatch -Sender $Sender -Batch $b -Result $res }
|            catch { if (-not $Sender.Failed) { $Sender.Failed = [string]$_.Exception.Message } }
|        }
|        if ($WaitOne -and -not $All) { return }
|    }
|}
|
|function Send-SILogIngestSenderCut {
|    <# Makes ONE post from the rows waiting: compressed and MEASURED; over the limit -> the last rows wait for the next post
|       (as many as the measurement says), never a half-empty post: a post that measures under 60% of the limit is not
|       sent yet (the ratio is learnt from it and the rows keep coming) -- unless -Final (the rows left at the end). #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [switch]$Final)
|    $rows = $Sender.Pending
|    if ($rows.Count -eq 0) { return }
|    $take = $rows.Count
|    $limit = [long][Math]::Floor($Sender.MaxBytes * $Sender.Fill)
|    while ($true) {
|        $raw = New-Object System.IO.MemoryStream
|        try {
|            $raw.WriteByte(0x5B)
|            for ($i = 0; $i -lt $take; $i++) { if ($i -gt 0) { $raw.WriteByte(0x2C) }; $b = $rows[$i]; $raw.Write($b, 0, $b.Length) }
|            $raw.WriteByte(0x5D)
|            $rawBytes = $raw.ToArray()
|        } finally { $raw.Dispose() }
|        $payload = if ($Sender.Compress) { ConvertTo-SILogGzip -Bytes $rawBytes } else { $rawBytes }
|        if ($Sender.Compress -and $rawBytes.Length -gt 0) { $Sender.Ratio = [Math]::Max(0.005, $payload.Length / [double]$rawBytes.Length) }
|        if (-not $Final -and $take -eq $rows.Count -and $payload.Length -lt [long]($limit * 0.6)) { return }   # too empty yet: wait for more rows
|        if ($payload.Length -le $limit -or ($payload.Length -le $Sender.MaxBytes -and $take -eq 1)) { break }
|        if ($take -eq 1) { throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f $payload.Length, $Sender.MaxBytes) }
|        # as many rows as the measured bytes per row allow, a little under (the next post takes the rest)
|        $take = [int][Math]::Max(1, [Math]::Min($take - 1, [Math]::Floor($take * ($limit * 0.98) / [double]$payload.Length)))
|    }
|    $batchRows = $rows.GetRange(0, $take)
|    $rows.RemoveRange(0, $take)
|    $Sender.PendingBytes = 2L; foreach ($b in $rows) { $Sender.PendingBytes += $b.Length + 1 }
|    $from = $Sender.Dispatched + 1
|    $Sender.Dispatched += $take
|    Send-SILogIngestSenderBatch -Sender $Sender -Payload $payload -Batch @{ Rows = $batchRows; Raw = $rawBytes.Length; From = $from; Refresh = $false }
|}
|
|function Send-SILogIngestSenderRows {
|    <# Adds serialised rows to the sender, in order; a post is made each time the rows waiting reach the measured size of a
|       full one. -From: re-sent rows (a 413 split) keep their numbers and go out at once. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)]$Rows, [long]$From = 0)
|    if ($From -gt 0) {
|        # a split batch: these rows go out as they are (each half measured again), ahead of the rows waiting
|        $keep = $Sender.Pending; $keepBytes = $Sender.PendingBytes
|        $Sender.Pending = New-Object 'System.Collections.Generic.List[byte[]]'; foreach ($b in $Rows) { [void]$Sender.Pending.Add($b) }
|        $saved = $Sender.Dispatched; $Sender.Dispatched = $From - 1
|        while ($Sender.Pending.Count -gt 0) { Send-SILogIngestSenderCut -Sender $Sender -Final }
|        $Sender.Dispatched = $saved + $Rows.Count
|        $Sender.Pending = $keep; $Sender.PendingBytes = $keepBytes
|        return
|    }
|    foreach ($b in $Rows) {
|        if (-not $Sender.Compress -and ($b.Length + 2) -gt $Sender.MaxBytes) {
|            throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f ($b.Length + 2), $Sender.MaxBytes)
|        }
|        # raw-bytes ceiling: the limit itself uncompressed; compressed, the fill level over the measured ratio
|        $ceiling = if ($Sender.Compress) { [long][Math]::Min(64MB, [Math]::Floor($Sender.MaxBytes * $Sender.Fill / $Sender.Ratio)) } else { [long][Math]::Floor($Sender.MaxBytes * $Sender.Fill) }
|        $add = $b.Length + $(if ($Sender.Pending.Count -gt 0) { 1 } else { 0 })
|        if ($Sender.Pending.Count -gt 0 -and ($Sender.PendingBytes + $add) -gt $ceiling) {
|            Send-SILogIngestSenderCut -Sender $Sender
|            if ($Sender.Failed) { throw $Sender.Failed }
|            $add = $b.Length + $(if ($Sender.Pending.Count -gt 0) { 1 } else { 0 })
|        }
|        [void]$Sender.Pending.Add($b); $Sender.PendingBytes += $add
|        $Sender.Accepted++
|    }
|    Receive-SILogIngestSenderResults -Sender $Sender
|    if ($Sender.Failed) { throw $Sender.Failed }
|}
|
|function Sync-SILogIngestSender {
|    <# Every row handed over is posted and answered (the rows waiting go out now). Throws when a post failed. #>
|    param([Parameter(Mandatory)][hashtable]$Sender)
|    while ($Sender.Pending.Count -gt 0 -and -not $Sender.Failed) { Send-SILogIngestSenderCut -Sender $Sender -Final }
|    Receive-SILogIngestSenderResults -Sender $Sender -All
|    if ($Sender.Failed) { throw $Sender.Failed }
|}
|
|function Invoke-SILogIngestGuardHeal {
|    <#
|        #733 (owner 2026-10-17: guards heal themselves): a table whose rows Log Analytics accepted IN FULL clears an earlier
|        "rows not accepted" of that table by itself. Once per table per process (the first full post), so the hot path pays one
|        state read per table, not one per post. Never throws; nothing when the guard code is not loaded.
|    #>
|    param([Parameter(Mandatory)][string]$Table)
|    try {
|        if (-not (Get-Command -Name Invoke-SIGuardHeal -ErrorAction Ignore)) { return }
|        if ($null -eq $script:SILogIngestHealed) { $script:SILogIngestHealed = @{} }
|        $t = $Table.ToLowerInvariant()
|        if ($script:SILogIngestHealed.ContainsKey($t)) { return }
|        $script:SILogIngestHealed[$t] = $true
|        $null = Invoke-SIGuardHeal -Checked @(@{ GuardId = 'ingest.rows.short-count'; Subject = $Table; Detail = ('Log Analytics accepted every row for {0}.' -f $Table) }) -Complete $true
|    } catch { }
|}
|
|function Complete-SILogIngestSender {
|    <#
|        The end of the hand-over: the rows waiting are posted, every post is answered, the workers are closed. The rows the
|        service CONFIRMED are counted against the rows handed over -- fewer throws (and is a guard event), as a short
|        synchronous post did. Returns @{ RowsPosted; RowsHandedOver; Posts; BytesPosted; BytesSent; MaxBytesSent; Retries; Split413 }.
|    #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = Get-SILogIngestSender -TableName $TableName
|    if ($null -eq $s) { return $null }
|    try { Sync-SILogIngestSender -Sender $s }
|    finally { Close-SILogIngestSender -TableName $TableName }
|    if ($s.Confirmed -ne $s.Accepted) {
|        if (Get-Command -Name Send-SIGuardEvent -ErrorAction Ignore) { $null = Send-SIGuardEvent -GuardId 'ingest.rows.short-count' -Outcome 'refused' -Subject ($s.Table + '_CL') -Detail ("Log Analytics accepted {0} of {1} row(s) for {2}_CL." -f $s.Confirmed, $s.Accepted, $s.Table) -Values @(@{ Name = 'rowsPosted'; Label = 'Rows accepted'; Measured = [long]$s.Confirmed; Limit = [long]$s.Accepted }, @{ Name = 'rowsGiven'; Label = 'Rows sent'; Measured = [long]$s.Accepted }) -HeldCount ([long]$s.Accepted - [long]$s.Confirmed) }
|        throw ("Posted {0} of {1} row(s) to {2}_CL -- the other rows are UNKNOWN, not posted." -f $s.Confirmed, $s.Accepted, $s.Table)
|    }
|    if ([long]$s.Accepted -gt 0) { Invoke-SILogIngestGuardHeal -Table ($s.Table + '_CL') }
|    [pscustomobject]@{ RowsPosted = $s.Confirmed; RowsHandedOver = $s.Accepted; Posts = $s.Posts; BytesPosted = $s.Bytes; BytesSent = $s.SentBytes; MaxBytesSent = $s.MaxSent; Retries = [int]$s.Gate['Retries']; Split413 = $s.Split413 }
|}
|
|function Send-SILogDataToSender {
|    <#
|        Send-SILogDataRest's rows through a sender: serialised EXACTLY as the synchronous path does (ConvertTo-Json -Depth 100
|        -Compress per row, UTF-8, in the order given) and handed over. Returns the synchronous path's result shape: RowsPosted
|        = the rows handed over (the rows CONFIRMED are counted by Complete-SILogIngestSender), BytesPosted = their JSON bytes.
|        When this run added columns to the rule and their check is due (Confirm-SILogNewColumns, after this call), every row
|        handed over is posted and answered first -- the check reads the rows back from Log Analytics.
|    #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][AllowEmptyCollection()][array]$Data, [string]$DcrName)
|    # #639: handed over a BATCH at a time -- the rows serialised so far are handed to the sender once they fill a post
|    # (its measured size), never the whole post serialised first and held as bytes beside the rows
|    $list = New-Object 'System.Collections.Generic.List[byte[]]'
|    $bytes = 1L; $count = 0L; $listBytes = 0L
|    $fill = 1.0; if ($Sender.ContainsKey('Fill') -and $Sender.Fill) { $fill = [double]$Sender.Fill }
|    $ratio = 1.0; if ($Sender.ContainsKey('Ratio') -and $Sender.Ratio) { $ratio = [double]$Sender.Ratio }
|    $max = 1MB; if ($Sender.ContainsKey('MaxBytes') -and $Sender.MaxBytes) { $max = [long]$Sender.MaxBytes }
|    $handAt = [long][Math]::Max(1, [Math]::Floor($max * $fill))
|    if ($Sender.Compress) { $handAt = [long][Math]::Min(64MB, [Math]::Floor($max * $fill / $ratio)) }
|    foreach ($row in $Data) {
|        $b = [System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -Depth 100 -InputObject $row -Compress))
|        [void]$list.Add($b); $bytes += $b.Length + 1; $listBytes += $b.Length + 1; $count++
|        if ($listBytes -ge $handAt) {
|            Send-SILogIngestSenderRows -Sender $Sender -Rows $list
|            $list = New-Object 'System.Collections.Generic.List[byte[]]'; $listBytes = 0L
|        }
|    }
|    if ($list.Count -gt 0) { Send-SILogIngestSenderRows -Sender $Sender -Rows $list }
|    $list = $null
|    if ($DcrName -and ($global:SI_LogIngestNewColumns -is [hashtable]) -and $global:SI_LogIngestNewColumns.ContainsKey($DcrName.ToLowerInvariant())) {
|        Sync-SILogIngestSender -Sender $Sender
|    }
|    [pscustomobject]@{ StatusCode = 204; RowsPosted = $count; BytesPosted = $bytes; Batches = 0; Table = ($Sender.Table + '_CL'); Stream = '' }
|}
|
|function Stop-SILogIngestSender {
|    <# After a failure: nothing more is posted; the posts in flight are answered (their rows count), the workers closed.
|       Returns the rows the service confirmed (the rows that DID reach Log Analytics). Never throws. #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = Get-SILogIngestSender -TableName $TableName
|    if ($null -eq $s) { return 0L }
|    try { $s.Pending.Clear(); Receive-SILogIngestSenderResults -Sender $s -All } catch { }
|    Close-SILogIngestSender -TableName $TableName
|    [long]$s.Confirmed
|}
|
|function Close-SILogIngestSender {
|    param([Parameter(Mandatory)][string]$TableName)
|    $c = Get-SILogIngestRunCache
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if (-not ($c.Senders -is [hashtable]) -or -not $c.Senders.ContainsKey($k)) { return }
|    $s = $c.Senders[$k]
|    foreach ($b in $s.InFlight.ToArray()) { try { if ($b.PS) { $b.PS.Stop(); $b.PS.Dispose() } } catch { } }
|    $s.InFlight.Clear()
|    if ($s.Pool) { try { $s.Pool.Close(); $s.Pool.Dispose() } catch { }; $s.Pool = $null }
|    $c.Senders.Remove($k)
|}
|
|function Send-SILogDataRest {
|    <#
|        Twin of Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output, over plain REST:
|          * the rule is found by NAME in the configured subscription + SI_DcrResourceGroup (or the one created this run);
|          * the post goes through the endpoint the RULE is bound to -- ingestion accepts nothing else (#199);
|          * POST {endpoint}/dataCollectionRules/{immutableId}/streams/Custom-{table}_CL?api-version=2023-01-01;
|          * batches are sized from the MEASURED JSON bytes of the rows (working rule 5: no fixed row counts), each under
|            the 1 MB limit -- compressed when $global:EnableCompressionDefault says so, measured after compression and
|            split again if over;
|          * 429 / 5xx retried in-run with Retry-After; any other 4xx fails at once with the response body;
|          * the rows posted are COUNTED against the rows given -- a shortfall throws, it is never reported as done.
|        Rows are serialised exactly as the module serialised them (ConvertTo-Json -Depth 100 -Compress per row).
|        -BatchAmount is accepted and ignored: a fixed row count is what working rule 5 forbids.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][AllowEmptyCollection()][array]$Data, [Parameter(Mandatory)][AllowEmptyString()][string]$DcrName,
|          [AllowEmptyString()][string]$DceName, [Parameter(Mandatory)][string]$TableName,
|          [string]$BatchAmount, [bool]$EnableUploadViaLogHub = $false, [string]$LogHubPath,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine', [string]$TenantId,
|          [Nullable[bool]]$EnableCompression = $null, [Nullable[bool]]$UseManagedIdentity = $null, [string]$ManagedIdentityClientId,
|          [string]$SubscriptionId, [string]$DcrResourceGroup, [long]$MaxPayloadBytes = 1MB)
|    $total = @($Data).Count
|    if ($total -eq 0) { return }
|    if ($null -eq $EnableCompression) { $EnableCompression = if ($null -ne $global:EnableCompressionDefault) { [bool]$global:EnableCompressionDefault } else { $false } }
|    $bound = @{}; foreach ($k in $PSBoundParameters.Keys) { $bound[$k] = $PSBoundParameters[$k] }
|    $auth = Resolve-SILogIngestAuth -Bound $bound
|    # #738: a sender started for this table takes the rows (in order, serialised exactly as below); its endpoint, rule and
|    # sign-in are resolved on its first call and reused
|    $sender = Get-SILogIngestSender -TableName $TableName
|    if ($sender -and $sender.Uri) {
|        if ([bool]$EnableCompression -ne [bool]$sender.Compress) { $sender = $null }   # never mixed in one sender
|        else { return (Send-SILogDataToSender -Sender $sender -Data $Data -DcrName $DcrName) }
|    }
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId -DcrResourceGroup $DcrResourceGroup
|
|    $dcr = Resolve-SILogDcrForTable -DcrName $DcrName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DcrRg -Auth $auth
|    if (-not $dcr) { throw ("Data collection rule '{0}' was not found in resource group '{1}' of subscription '{2}', so nothing was posted." -f $DcrName, $scope.DcrRg, $scope.Subscription) }
|    $immutableId = [string]$dcr.properties.immutableId
|    if (-not $immutableId) { throw ("Data collection rule '{0}' has no immutable id yet, so nothing was posted." -f $DcrName) }
|    $stream = Get-SILogStreamName -TableName $TableName
|    if (-not ($dcr.properties.streamDeclarations -and $dcr.properties.streamDeclarations.PSObject.Properties[$stream])) {
|        $first = @(@($dcr.properties.dataFlows)[0].streams)[0]
|        if ($first) { $stream = [string]$first }
|    }
|    $endpoint = $null
|    $boundDce = [string]$dcr.properties.dataCollectionEndpointId
|    if ($boundDce) {
|        $dce = Invoke-SILogArm -Path $boundDce -ApiVersion (Get-SILogArmApiVersion Dce) -Auth $auth -AllowNotFound
|        if ($dce) { $endpoint = [string]$dce.properties.logsIngestion.endpoint }
|    }
|    if (-not $endpoint -and $dcr.properties.endpoints -and $dcr.properties.endpoints.logsIngestion) { $endpoint = [string]$dcr.properties.endpoints.logsIngestion }
|    if (-not $endpoint -and $DceName) {
|        $dce = Find-SILogResourceByName -Kind Dce -Name $DceName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DceRg -Auth $auth -AnyResourceGroupWhenMissing
|        if ($dce) { $endpoint = [string]$dce.properties.logsIngestion.endpoint }
|    }
|    if (-not $endpoint) { throw ("No ingestion endpoint for data collection rule '{0}' (not bound to an endpoint, and '{1}' was not found), so nothing was posted." -f $DcrName, $DceName) }
|
|    $authText = switch ($auth.Mode) { 'ManagedIdentity' { 'Auth=ManagedIdentity' } 'Certificate' { 'Auth=SPN-Cert' } 'Secret' { 'Auth=SPN' } 'Support' { 'Auth=InvardiaSupport' } default { 'Auth=Run' } }
|    $state = @{
|        Uri = ('{0}/dataCollectionRules/{1}/streams/{2}?api-version=2023-01-01' -f $endpoint.TrimEnd('/'), $immutableId, $stream)
|        Auth = $auth; Compress = [bool]$EnableCompression; MaxBytes = $MaxPayloadBytes; Ratio = 1.0
|        Posted = 0; Bytes = 0L; Batches = 0; Total = $total; Table = $TableName; AuthText = $authText
|    }
|    if ($sender) {
|        $sender.Uri = $state.Uri; $sender.Auth = $auth; $sender.AuthText = $authText; $sender.Compress = [bool]$EnableCompression
|        $sender.MaxBytes = [long][Math]::Min([double]$sender.MaxBytes, [double]$MaxPayloadBytes)
|        return (Send-SILogDataToSender -Sender $sender -Data $Data -DcrName $DcrName)
|    }
|    $batch = New-Object 'System.Collections.Generic.List[byte[]]'
|    $batchBytes = 2
|    foreach ($row in $Data) {
|        $b = [System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -Depth 100 -InputObject $row -Compress))
|        if (-not $state.Compress -and ($b.Length + 2) -gt $MaxPayloadBytes) {
|            throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f ($b.Length + 2), $MaxPayloadBytes)
|        }
|        # raw-bytes ceiling: the limit itself uncompressed; compressed, the limit over the measured ratio (90% margin)
|        $ceiling = if ($state.Compress) { [long][Math]::Min(64MB, [Math]::Floor($MaxPayloadBytes / $state.Ratio * 0.9)) } else { $MaxPayloadBytes }
|        $add = $b.Length + $(if ($batch.Count -gt 0) { 1 } else { 0 })
|        if ($batch.Count -gt 0 -and ($batchBytes + $add) -gt $ceiling) {
|            Send-SILogIngestBatch -Rows $batch -State $state
|            $batch = New-Object 'System.Collections.Generic.List[byte[]]'; $batchBytes = 2; $add = $b.Length
|        }
|        [void]$batch.Add($b); $batchBytes += $add
|    }
|    if ($batch.Count -gt 0) { Send-SILogIngestBatch -Rows $batch -State $state }
|    if ($state.Posted -ne $total) {
|        # #277: the short count is a guard trip -- mailed and reported (never instead of the throw)
|        if (Get-Command -Name Send-SIGuardEvent -ErrorAction Ignore) { $null = Send-SIGuardEvent -GuardId 'ingest.rows.short-count' -Outcome 'refused' -Subject ($TableName + '_CL') -Detail ("Log Analytics accepted {0} of {1} row(s) for {2}_CL." -f $state.Posted, $total, $TableName) -Values @(@{ Name = 'rowsPosted'; Label = 'Rows accepted'; Measured = [long]$state.Posted; Limit = [long]$total }, @{ Name = 'rowsGiven'; Label = 'Rows sent'; Measured = [long]$total }) -HeldCount ([long]$total - [long]$state.Posted) }
|        throw ("Posted {0} of {1} row(s) to {2}_CL -- the other rows are UNKNOWN, not posted." -f $state.Posted, $total, $TableName)
|    }
|    if ([long]$total -gt 0) { Invoke-SILogIngestGuardHeal -Table ($TableName + '_CL') }
|    # BytesPosted: the uncompressed JSON bytes of the rows posted -- a caller that posts in parts sizes its next part from it
|    return [pscustomobject]@{ StatusCode = 204; RowsPosted = $state.Posted; BytesPosted = $state.Bytes; Batches = $state.Batches; Table = ($TableName + '_CL'); Stream = $stream }
|}
'@ }
$__siSupportFiles['auth/Find-SICertificate.ps1'] = @{ Sha256 = '3778fc328c239b499738360e6b4fb31eb3109db39c3a9a9d8f5a02a228ad58d8'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- find the engine SPN's certificate on ANY host, and bring one into a container (#209).
|
|    KEY POINT: THE `Cert:` DRIVE IS A WINDOWS CONVENIENCE; [X509Store] IS THE AUTHORITY. The drive does not exist
|    in a Linux container at all (pwsh on Linux has no certificate provider), and on Windows it can vanish
|    from a PS 5.1 child that inherited a pwsh 7 PSModulePath (framework finding AUTH-1). Five ingest sites
|    looked a thumbprint up through the drive ONLY, so in a container the lookup always "missed", the store
|    location fell back to LocalMachine, and certificate sign-in could not work there at all.
|
|    Every function here uses the drive when it exists -- exactly what the engines did before -- and the
|    X509Store only when it does not, so a Windows VM with its certificate in LocalMachine\My resolves the
|    same certificate, from the same store, as it always has.
|
|    Functions:
|      Get-SICertificateFromStore    -- one thumbprint -> @{ Certificate; StoreLocation } or $null
|      Get-SICertStoreLocation       -- 'LocalMachine' / 'CurrentUser' for the log-ingestion sign-in (default LocalMachine)
|      Get-SICertificateClientToken  -- client_credentials with a certificate-signed assertion (no Cert: drive)
|      Import-SIContainerCertificate -- a base64 PFX (Key Vault reference) -> CurrentUser\My + a PFX file
|
|    PS 5.1 safe: no ?. / ??, no ImportFromPem.
|#>
|
|function Test-SICertDriveAvailable {
|    <# The Windows certificate provider is loaded in this process. A seam for the tests. #>
|    return [bool](Get-PSDrive -Name Cert -ErrorAction SilentlyContinue)
|}
|
|function Get-SICertificateFromStore {
|    <#
|        Find a certificate WITH a private key by thumbprint, LocalMachine first, then CurrentUser -- the order
|        every SI engine already used. Returns @{ Certificate; StoreLocation } or $null.
|
|        -HasCertDrive and -OpenStore are test seams: -OpenStore takes a store location and returns the
|        certificates in its My store.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyString()][string]$Thumbprint,
|        [string[]]$StoreLocations = @('LocalMachine', 'CurrentUser'),
|        [scriptblock]$HasCertDrive,
|        [scriptblock]$OpenStore
|    )
|    $clean = ($Thumbprint -replace '\s', '').ToUpperInvariant()
|    if ([string]::IsNullOrWhiteSpace($clean)) { return $null }
|    if (-not $HasCertDrive) { $HasCertDrive = { Test-SICertDriveAvailable } }
|    if (-not $OpenStore) {
|        $OpenStore = {
|            param([string]$Location)
|            $x = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', $Location)
|            try {
|                $x.Open('ReadOnly')
|                return @($x.Certificates)
|            } finally { $x.Close() }
|        }
|    }
|    $drive = [bool](& $HasCertDrive)
|    foreach ($loc in $StoreLocations) {
|        $found = $null
|        if ($drive) {
|            $found = Get-ChildItem "Cert:\$loc\My" -ErrorAction SilentlyContinue |
|                     Where-Object { $_.Thumbprint -eq $clean -and $_.HasPrivateKey } |
|                     Select-Object -First 1
|        } else {
|            try {
|                $found = @(& $OpenStore $loc | Where-Object { $_ -and $_.Thumbprint -eq $clean -and $_.HasPrivateKey })[0]
|            } catch {
|                Write-Verbose ("certificate store {0}\My unreadable: {1}" -f $loc, $_.Exception.Message)
|            }
|        }
|        if ($found) { return [pscustomobject]@{ Certificate = $found; StoreLocation = $loc } }
|    }
|    return $null
|}
|
|function Get-SICertStoreLocation {
|    <#
|        The store the log-ingestion sign-in should be told to look in. Same answer the five ingest sites computed
|        through the Cert: drive (LocalMachine when nothing is found), now also right where the drive is
|        missing.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyString()][string]$Thumbprint,
|        [scriptblock]$HasCertDrive,
|        [scriptblock]$OpenStore
|    )
|    $hit = Get-SICertificateFromStore -Thumbprint $Thumbprint -HasCertDrive $HasCertDrive -OpenStore $OpenStore
|    if ($hit) { return [string]$hit.StoreLocation }
|    return 'LocalMachine'
|}
|
|function Get-SICertificateClientToken {
|    <#
|        An access token for -Resource via client_credentials with a certificate-signed JWT assertion -- the
|        grant Get-SIGraphToken and the log ingestion already use, without the Cert: drive. Returns the
|        token string. -Invoke is a test seam: { param($Uri, $Body) } returning the token response.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$TenantId,
|        [Parameter(Mandatory)][string]$ClientId,
|        [Parameter(Mandatory)][string]$Thumbprint,
|        [Parameter(Mandatory)][string]$Resource,
|        [scriptblock]$Invoke
|    )
|    $hit = Get-SICertificateFromStore -Thumbprint $Thumbprint
|    if (-not $hit) { throw ("certificate '{0}' was not found with a private key in LocalMachine\My or CurrentUser\My." -f (($Thumbprint -replace '\s', '').ToUpperInvariant())) }
|    $cert = $hit.Certificate
|
|    $scope = if ($Resource -match '/\.default$') { $Resource } else { ($Resource.TrimEnd('/') + '/.default') }
|    $tokenUri = 'https://login.microsoftonline.com/{0}/oauth2/v2.0/token' -f $TenantId
|    $b64url = { param([byte[]]$Bytes) [Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_') }
|    $now = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
|    $header = @{ alg = 'RS256'; typ = 'JWT'; x5t = (& $b64url $cert.GetCertHash()) } | ConvertTo-Json -Compress
|    $claims = @{ aud = $tokenUri; iss = $ClientId; sub = $ClientId; jti = [guid]::NewGuid().ToString(); nbf = $now; exp = ($now + 600) } | ConvertTo-Json -Compress
|    $enc = [System.Text.Encoding]::UTF8
|    $unsigned = '{0}.{1}' -f (& $b64url $enc.GetBytes($header)), (& $b64url $enc.GetBytes($claims))
|    $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
|    if (-not $rsa) { throw ("certificate '{0}' has no usable RSA private key." -f $cert.Thumbprint) }
|    $sig = $rsa.SignData($enc.GetBytes($unsigned), [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
|    $body = @{
|        client_id             = $ClientId
|        scope                 = $scope
|        client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
|        client_assertion      = ('{0}.{1}' -f $unsigned, (& $b64url $sig))
|        grant_type            = 'client_credentials'
|    }
|    $resp = if ($Invoke) { & $Invoke $tokenUri $body }
|            # a time limit: without one this call waits for as long as the other side stays silent (PowerShell 7 has no default)
|            else { Invoke-RestMethod -Method Post -Uri $tokenUri -Body $body -ContentType 'application/x-www-form-urlencoded' -TimeoutSec 60 }
|    if (-not $resp.access_token) { throw 'the token endpoint returned no access_token.' }
|    return [string]$resp.access_token
|}
|
|function Get-SIContainerCertificateKeyFlags {
|    <# PURE. The key flags the container imports the SPN's PFX with: Exportable + PersistKeySet (the store keeps the key for
|       the life of the run). One place, so a test can pin them. #>
|    [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor
|        [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet
|}
|
|function Import-SIContainerCertificate {
|    <#
|        CONTAINER ONLY. The SPN's PFX arrives as a Key Vault-referenced secret (base64), exactly as the SI
|        updater receives its own. This puts it where every engine looks:
|          * CurrentUser\My, through [X509Store] (the only certificate store a Linux container has), so
|            Get-SIGraphToken, the ledger and the log ingestion find it by thumbprint;
|          * a PFX file (owner-only), so Connect-SIAzAccount -CertificatePath can sign in with it -- az and
|            the sign-in remember the PATH, not the key, so the file is kept for the life of the run.
|        Returns @{ Thumbprint; PfxPath }. Never prints the certificate or its password.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$PfxBase64,
|        [string]$Password,
|        [string]$Directory = [IO.Path]::GetTempPath(),
|        [switch]$SkipStore,
|        # TESTS ONLY: a Windows test session that cannot persist a private key (no DPAPI master key) imports with
|        # EphemeralKeySet instead. No caller in the product passes it: the container always uses Get-SIContainerCertificateKeyFlags.
|        [Parameter(DontShow)][AllowNull()][Nullable[System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]]$KeyStorageFlags = $null
|    )
|    $bytes = [Convert]::FromBase64String(($PfxBase64 -replace '\s', ''))
|    $flags = if ($null -ne $KeyStorageFlags) { [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]$KeyStorageFlags } else { Get-SIContainerCertificateKeyFlags }
|    # A Key Vault certificate's secret is a password-less PFX; '' opens those on both .NET hosts.
|    $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes, [string]$Password, $flags)
|    if (-not $cert.HasPrivateKey) { throw 'the SPN certificate (SI_SPN_CERT_PFX_B64) carries no private key.' }
|
|    if (-not $SkipStore) {
|        $store = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', 'CurrentUser')
|        try {
|            $store.Open('ReadWrite')
|            $store.Add($cert)
|        } finally { $store.Close() }
|    }
|
|    $pfxPath = Join-Path $Directory ('si-spn-' + [guid]::NewGuid().ToString('N') + '.pfx')
|    [IO.File]::WriteAllBytes($pfxPath, $bytes)
|    if ($PSVersionTable.PSVersion.Major -ge 6 -and -not $IsWindows) { try { & chmod 600 $pfxPath } catch { } }
|    return [pscustomobject]@{ Thumbprint = [string]$cert.Thumbprint; PfxPath = $pfxPath }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-ErrorClass.ps1'] = @{ Sha256 = 'ab3ed267218c640b0e672f593af5d33a61146cc96980f39dc70ee56e2f8bd92d'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- WHAT KIND OF FAILURE WAS IT: one error class per failed run, for the telemetry `run` record.
|
|    ExitReason says only success / success-partial / error / settings-error. A release-health view needs to tell "a
|    permission is missing" from "the service was throttling" from "the query is broken", without free text (anonymous
|    installs send no error text at all). Get-SIErrorClass maps an error to exactly ONE value of a CLOSED list -- the list
|    agreed with the receiving side; anything not recognised is 'unknown', never a guess.
|
|    It is built on the classifiers SecurityInsight already trusts:
|      * SI-KqlError.ps1 -- what a Log Analytics failure REALLY said (the response body, not "BadRequest") and whether
|        it was a missing table;
|      * working rule 4 / Risk Analysis' bucket classifier -- the recognised PLATFORM prefixes (a cancellation or a
|        service-side entity resolution carries the service's generic "Fix semantic errors" tail and is NOT a query
|        defect), then syntax / semantic / type errors = query defect, then throttle, then timeout / 5xx.
|
|    The order of the checks is the contract (first match wins):
|      settings-error > guard-refused > out-of-memory > database-full > licence-invalid > mi-unavailable > sql-login > config-missing > ingest-short-count >
|      table-missing > platform prefix (timeout / 5xx) > kql-query-defect > throttled > ingest-4xx >
|      401 / 403 by service > ai-error > platform-timeout > platform-5xx > unknown.
|    A 401 from Microsoft Graph is graph-401; a 401 from another service means the same thing as its 403 there (access
|    refused) and gets that service's -403 class.
|
|    PURE. No network. PS 5.1 safe.
|#>
|
|if (-not (Get-Command -Name Get-SIKqlErrorText -ErrorAction SilentlyContinue)) {
|    . ([System.IO.Path]::Combine($PSScriptRoot, 'SI-KqlError.ps1'))
|}
|
|# The closed list, exactly as agreed (#226). Get-SIErrorClass returns one of these and nothing else.
|function Get-SIErrorClassesState {
|    <# The value of $script:SIErrorClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIErrorClasses) { $script:SIErrorClasses = @(
|    'graph-401', 'graph-403', 'defender-403', 'arm-403', 'kv-403', 'storage-403', 'sql-login', 'mi-unavailable',
|    'throttled', 'platform-timeout', 'platform-5xx', 'kql-query-defect', 'table-missing', 'ingest-4xx',
|    'ingest-short-count', 'settings-error', 'config-missing', 'licence-invalid', 'ai-error',
|    # UPLINK-FIX (Invardia, 2026-10-07): a run a guard REFUSED (nothing written, by design). The run's message is
|    # '<guard id> refused: <why>' (Get-SIGuardRefusalText) -- its own class, so a refusal never reads as 'unknown'.
|    'guard-refused',
|    # #641 (owner 2026-10-13): a Risk Analysis report that is NOT COMPLETE in its run (its rows do not match what the source
|    # holds, or it is not in the run at all) -- set by Risk Analysis itself, never derived from a message
|    'report-incomplete',
|    # #702 (1) (customer B 2026-10-15): the process ran out of memory. Its own class, never platform-timeout -- a platform
|    # class is retried in-run on the same size, which runs out again; the job-size rule raises the job one band instead.
|    # (Invardia's receiver takes any ^[a-z0-9-]{1,40}$ class -- packages/core/src/uplink.ts.)
|    'out-of-memory',
|    # #904 (a large install 2026-10-26): Azure SQL refused a write because the database reached its maximum size (1105,
|    # 40544, "has reached its size quota"). Its own class -- never 'unknown' -- so a part that failed on it opens a ticket.
|    'database-full',
|    # #913 (the ride test install 2026-10-27): an Azure SQL transient (9001 log not available, 40613 / 40501 / 40197 /
|    # 49918-49920, 4060 during a failover, 10928 / 10929, a reset connection) that did not pass within its bounded retry.
|    # Set by the caller that retried it (the pipeline runner's lock), never derived from a text: not a product defect.
|    'transient-sql',
|    # 3.0.30: the web app's identity has no grant on its Key Vault key (the updater only checks it; setup makes it) -- the
|    # customer's action with the command, never arm-403 (that is a real 403 answer). Set by the caller, never derived from a text.
|    'grant-missing',
|    'unknown'
|) }
|    , $script:SIErrorClasses
|}
|$script:SIErrorClasses = $null; $null = Get-SIErrorClassesState
|
|# #904: the numbers of Azure SQL's "the database is full" refusal (1105: no space in the filegroup; 40544: the database
|# reached its size quota; 1101: no new page could be allocated)
|function Get-SIDatabaseFullNumbersState {
|    <# The value of $script:SIDatabaseFullNumbers, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIDatabaseFullNumbers) { $script:SIDatabaseFullNumbers = @(1105, 40544, 1101) }
|    , $script:SIDatabaseFullNumbers
|}
|$script:SIDatabaseFullNumbers = $null; $null = Get-SIDatabaseFullNumbersState
|
|# Risk Analysis' recognised platform-failure prefixes (RA-GraphHunting.ps1, $script:RAPlatformFailurePrefixes). Read
|# from there when Risk Analysis is loaded, so the two can never disagree; this copy serves every other engine. A test
|# compares the two lists.
|function Get-SIErrorPlatformPrefixesState {
|    <# The value of $script:SIErrorPlatformPrefixes, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIErrorPlatformPrefixes) { $script:SIErrorPlatformPrefixes = @(
|    @{ Pattern = 'Query cancelled on creation'; Class = 'platform-timeout' }
|    @{ Pattern = 'ScalarEvaluator\.Evaluate failed'; Class = 'platform-timeout' }
|    @{ Pattern = 'Errors occurred while resolving remote entities'; Class = 'platform-5xx' }
|) }
|    , $script:SIErrorPlatformPrefixes
|}
|$script:SIErrorPlatformPrefixes = $null; $null = Get-SIErrorPlatformPrefixesState
|
|function Get-SIErrorClasses { (Get-SIErrorClassesState) }
|
|function Test-SIDatabaseFullError {
|    <#
|        PURE. #904: did Azure SQL refuse a write because the database is FULL? -Value: an ErrorRecord, an exception (its
|        SqlException numbers and inner exceptions are read) or a text. SQL 1105 / 40544 / 1101, "has reached its size quota",
|        "filegroup is full", "Could not allocate space" / "Could not allocate a new page".
|    #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value) { return $false }
|    $ex = if ($Value -is [System.Exception]) { $Value } elseif ($Value -is [System.Management.Automation.ErrorRecord]) { $Value.Exception } else { $null }
|    $texts = New-Object System.Collections.Generic.List[string]
|    while ($ex) {
|        if ($ex -is [System.Data.SqlClient.SqlException]) { foreach ($er in @($ex.Errors)) { if ((Get-SIDatabaseFullNumbersState) -contains [int]$er.Number) { return $true } } }
|        $texts.Add([string]$ex.Message); $ex = $ex.InnerException
|    }
|    if (-not $texts.Count) { $texts.Add([string]$Value) }
|    $t = $texts -join ' | '
|    return [bool]($t -match '(?i)has reached its size quota|filegroup is full|Could not allocate (space|a new page)|\b(Error|Msg|Number)[ :=]*(1105|40544)\b|\((1105|40544)\)')
|}
|
|function Get-SITransientKind {
|    <#
|        PURE. THE ONE DECISION of what a failed call or a failure text REALLY was (2026-10-22: a "Connection timed out" to
|        SI's own storage was reported to the owner as "Microsoft throttled this run"):
|          throttled    Microsoft asked us to slow down -- ONLY a real throttling answer: HTTP 429, "Too Many Requests", a
|                       rate limit, SQL 40501 / 10928 / 10929 (the service is busy / resource limit)
|          timeout      no answer in time: HTTP 408 / 504, SQL -2, "timed out" / "timeout" / a cancelled task
|          unavailable  the service could not be reached or failed: HTTP 500 / 502 / 503, no answer at all (status 0 without a
|                       timeout), a reset / refused / closed connection, a host that does not resolve, SQL 40613 / 40197 /
|                       49918-49920 / 10053 / 10054 / 233 / 64
|          error        anything else (a refusal, a bug, a bad request) -- never retried as transient
|        -StatusCode (an HTTP status; 0 = no answer; -1 = not known), -Message (the error text), -SqlNumber (SqlException numbers).
|        SecurityInsight's OWN customer sentence ("Microsoft throttled this run ...") is taken out of the text first, so a
|        re-read log never classifies itself.
|    #>
|    param([int]$StatusCode = -1, [AllowNull()][AllowEmptyString()][string]$Message = '', [AllowNull()][int[]]$SqlNumber = @())
|    $t = ([string]$Message) -replace '(?i)Microsoft throttled this run[^|]*', ''
|    $sql = @($SqlNumber | Where-Object { $null -ne $_ })
|    if ($StatusCode -eq 429 -or @($sql | Where-Object { $_ -in 40501, 10928, 10929 }).Count -gt 0) { return 'throttled' }
|    if ($t -match '(?i)\b429\b|Too ?Many ?Requests|\bthrottl|rate limit|RequestRateTooLarge') { return 'throttled' }
|    if ($StatusCode -in 408, 504 -or $sql -contains -2) { return 'timeout' }
|    if ($t -match '(?i)timed? ?out|timeout|TaskCanceledException|A task was canceled|operation was canceled|\b504\b|Gateway Time-?out|\b408\b') { return 'timeout' }
|    if ($StatusCode -in 500, 502, 503 -or $StatusCode -eq 0 -or @($sql | Where-Object { $_ -in 40613, 40197, 49918, 49919, 49920, 10053, 10054, 233, 64 }).Count -gt 0) { return 'unavailable' }
|    if ($t -match '(?i)\b50[0-3]\b|Internal ?Server ?Error|Bad Gateway|Service ?Unavailable|ServiceUnavailable|temporarily unavailable|is not currently available|forcibly closed|connection (was )?reset|Connection reset by peer|actively refused|No such host is known|Name or service not known|transport-level error|Unable to connect to the remote server') { return 'unavailable' }
|    'error'
|}
|
|function Test-SIOutOfMemoryText {
|    <# PURE. Does a failure text (or an exception / ErrorRecord, read with its inner exceptions) say the process ran out of
|       memory? .NET's OutOfMemoryException (also wrapped: "Exception calling ... : Exception of type
|       'System.OutOfMemoryException' was thrown", "Cannot process argument transformation on parameter 'TimeoutSec'. ..."),
|       Container Apps' OOMKilled, or SecurityInsight's own "out of memory" wording. #702 (1). #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value) { return $false }
|    $ex = if ($Value -is [System.Exception]) { $Value } elseif ($Value -is [System.Management.Automation.ErrorRecord]) { $Value.Exception } else { $null }
|    while ($ex) { if ($ex -is [System.OutOfMemoryException]) { return $true }; $ex = $ex.InnerException }
|    $t = if ($Value -is [System.Management.Automation.ErrorRecord]) { [string]$Value.Exception } else { [string]$Value }
|    return [bool]($t -match '(?i)OutOfMemoryException|\bOOMKilled\b|\bout of memory\b')
|}
|
|# WHO FIXES IT (framework §8.5 CLOSE-LOOP, Invardia 046): the classes whose fix is the CUSTOMER's configuration -- a
|# permission or consent the install's identity does not have (the five -403 classes), a licence or licensed feature it
|# lacks (licence-invalid), a setting the customer must set (config-missing, settings-error). Everything else -- sign-in
|# and token trouble, a missing table, ingestion, throttling, timeouts, service errors, guard refusals, unknown -- stays a
|# product defect: a class is put here only when its own definition above says the customer's configuration is the cause.
|function Get-SICustomerConfigClassesState {
|    <# The value of $script:SICustomerConfigClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SICustomerConfigClasses) { $script:SICustomerConfigClasses = @('graph-403', 'defender-403', 'arm-403', 'kv-403', 'storage-403', 'licence-invalid', 'config-missing', 'settings-error', 'grant-missing') }
|    , $script:SICustomerConfigClasses
|}
|$script:SICustomerConfigClasses = $null; $null = Get-SICustomerConfigClassesState
|# #913: the classes that are nobody's fix -- an Azure SQL transient that did not pass within its bounded retry. No FixKind:
|# never a fix request, never a red alert (the next wake-up runs as usual).
|function Get-SINoFixClassesState {
|    <# The value of $script:SINoFixClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SINoFixClasses) { $script:SINoFixClasses = @('transient-sql') }
|    , $script:SINoFixClasses
|}
|$script:SINoFixClasses = $null; $null = Get-SINoFixClassesState
|
|function Get-SICustomerConfigClasses { (Get-SICustomerConfigClassesState) }
|
|function Get-SIErrorFixKind {
|    <#
|        PURE. The FixKind of a failed report's error class: 'customer-config' for a class on the customer-configuration list,
|        'product-defect' for every other class of the closed list (and anything not on it), '' when there is no class.
|    #>
|    param([AllowEmptyString()][AllowNull()][string]$ErrorClass)
|    $c = "$ErrorClass".Trim().ToLowerInvariant()
|    if (-not $c) { return '' }
|    if ((Get-SINoFixClassesState) -contains $c) { return '' }
|    if ((Get-SICustomerConfigClassesState) -contains $c) { return 'customer-config' }
|    'product-defect'
|}
|
|function Get-SIErrorService {
|    <# PURE. Which service a failure came from, by the host or the wording it carries: graph | defender | arm | kv |
|       storage | sql | ingest | ai | loganalytics | ''. #>
|    param([AllowEmptyString()][string]$Text)
|    $t = [string]$Text
|    if ($t -match '(?i)ingest\.monitor\.azure\.com|Logs Ingestion|log ingestion|dataCollectionRules|\bDCR\b|\bDCE\b|InvalidTransformOutput') { return 'ingest' }
|    if ($t -match '(?i)openai\.azure\.com|\bOpenAI\b|content_filter|context_length_exceeded|DeploymentNotFound|chat/completions') { return 'ai' }
|    if ($t -match '(?i)api\.securitycenter\.microsoft\.com|api\.security\.microsoft\.com|security/runHuntingQuery|advanced hunting|Microsoft Defender|\bMachine\.Read\.All\b|\bThreatHunting\.Read\.All\b') { return 'defender' }
|    if ($t -match '(?i)\.vault\.azure\.net|Key ?Vault|ForbiddenByRbac|ForbiddenByPolicy|secrets get permission|getSecret/action') { return 'kv' }
|    if ($t -match '(?i)\.(blob|table|queue|file|dfs)\.core\.windows\.net|AuthorizationPermissionMismatch|AuthorizationFailure|storage account') { return 'storage' }
|    if ($t -match '(?i)database\.windows\.net|SqlException|SqlClient|\bLogin failed\b') { return 'sql' }
|    if ($t -match '(?i)management\.azure\.com|AuthorizationFailed|Microsoft\.[A-Za-z]+/[A-Za-z]+/[A-Za-z/]*(read|write|action)|\bAzure Resource Manager\b|LinkedAuthorizationFailed') { return 'arm' }
|    if ($t -match '(?i)graph\.microsoft\.com|Authorization_RequestDenied|Microsoft Graph|InvalidAuthenticationToken') { return 'graph' }
|    if ($t -match '(?i)api\.loganalytics|loganalytics\.io|Log Analytics|SEM\d{4}|SYN\d{4}') { return 'loganalytics' }
|    ''
|}
|
|function Get-SIErrorLines {
|    <#
|        PURE. A failed run's own words from its log (a run transcript, a console tail): the error that ENDED it -- the LAST
|        [ERROR] / exception / failed / refused / denied / status-code block (transcript TerminatingError markers and WARNING:
|        lines only when nothing else is there), and the lines after it up to -Max, else -- no such line --
|        the LAST -Max lines that carry text. Transcript headers / footers and the ******** frames are dropped. Never the whole
|        log: the uplink carries a few lines, and the caller redacts them (ConvertTo-AitUplinkRedacted). '' for no text.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][string[]]$Lines = @(), [int]$Max = 8, [int]$MaxChars = 1800)
|    $keep = New-Object System.Collections.Generic.List[string]
|    $inHeader = $false
|    foreach ($raw in @($Lines)) {
|        $l = ([string]$raw).TrimEnd()
|        if (-not $l.Trim()) { continue }
|        if ($l -match '^\*{10,}$') { $inHeader = -not $inHeader; continue }
|        if ($inHeader) { continue }
|        if ($l -match '^(PowerShell|Windows PowerShell) transcript (start|end)|^(Start|End) time: \d{14}|^Transcript started, output file is') { continue }
|        $keep.Add($l.Trim())
|    }
|    if (-not $keep.Count) { return '' }
|    $err = '(?i)\[(ERROR|FAIL(ED)?|FATAL)\]|\bERROR\b|Exception|\bfailed\b|could not|cannot|refused|denied|Forbidden|Unauthorized|Login failed|\b(40[0-9]|429|50[0-4])\b|throttl|timed? ?out'
|    # The error that ENDED the run, not the first one in the log: every error-looking line is a candidate; the
|    # transcript's own "PS>TerminatingError(...)" / ">> TerminatingError(...)" markers (written for an error the code
|    # CAUGHT and went on after) and WARNING: lines count only when the log has no other error line. The LAST such line
|    # is taken, from the start of its block (the error lines right before it), and the lines after it up to -Max.
|    $isErr = { param($s) $s -match $err -and $s -notmatch '(?i)^\s*(VERBOSE|DEBUG)\b|\b0 (failed|errors?)\b' }
|    $isWeak = { param($s) $s -match '(?i)^\s*(PS>|>>\s*)TerminatingError\(|^\s*WARNING:' }
|    $strong = -1; $weak = -1
|    for ($i = 0; $i -lt $keep.Count; $i++) {
|        if (-not (& $isErr $keep[$i])) { continue }
|        if (& $isWeak $keep[$i]) { $weak = $i } else { $strong = $i }
|    }
|    $first = if ($strong -ge 0) { $strong } else { $weak }
|    if ($first -ge 0) {
|        $wantWeak = ($strong -lt 0)
|        while ($first -gt 0 -and (& $isErr $keep[$first - 1]) -and ($wantWeak -or -not (& $isWeak $keep[$first - 1]))) { $first-- }
|    }
|    $pick = if ($first -ge 0) { @($keep.GetRange($first, [Math]::Min($Max, $keep.Count - $first))) } else { @($keep.GetRange([Math]::Max(0, $keep.Count - $Max), [Math]::Min($Max, $keep.Count))) }
|    $t = ($pick -join "`n")
|    if ($t.Length -gt $MaxChars) { $t = $t.Substring(0, $MaxChars) }
|    $t
|}
|
|function Get-SIErrorRecordSummary {
|    <# PURE. The words of a caught error, never empty: its message, else its exception type + error id + where it was
|       raised (an exception thrown without a message reached Invardia as an empty text -- si-trend x5). #>
|    param([AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $ex = if ($ErrorRecord -is [System.Exception]) { $ErrorRecord } elseif ($ErrorRecord.PSObject.Properties['Exception']) { $ErrorRecord.Exception } else { $null }
|    $m = if ($ex) { "$($ex.Message)".Trim() } else { "$ErrorRecord".Trim() }
|    if ($m) { return $m }
|    $parts = New-Object System.Collections.Generic.List[string]
|    if ($ex) { $parts.Add($ex.GetType().FullName) }
|    if ($ErrorRecord.PSObject.Properties['FullyQualifiedErrorId'] -and "$($ErrorRecord.FullyQualifiedErrorId)".Trim()) { $parts.Add("id $($ErrorRecord.FullyQualifiedErrorId)") }
|    if ($ErrorRecord.PSObject.Properties['InvocationInfo'] -and $ErrorRecord.InvocationInfo -and $ErrorRecord.InvocationInfo.ScriptName) { $parts.Add(('at {0}:{1}' -f (Split-Path -Leaf $ErrorRecord.InvocationInfo.ScriptName), $ErrorRecord.InvocationInfo.ScriptLineNumber)) }
|    if (-not $parts.Count) { return 'an error without a message' }
|    'an error without a message (' + ($parts -join ', ') + ')'
|}
|
|function Get-SIErrorClass {
|    <#
|        PURE. The error class of one failure -- exactly one value of Get-SIErrorClasses.
|          -ErrorRecord  an ErrorRecord or an exception (its message, response body, typed body and inner exceptions are
|                        all read -- Get-SIKqlErrorText)
|          -Message      a text (a run-health ErrorMessage, a log line)
|          -ExitReason   the run's ExitReason: 'settings-error' is its own class whatever the text says
|          -Service      a hint when the caller knows which service it called (graph, defender, arm, kv, storage, sql,
|                        ingest, ai) -- used when the text does not name one
|    #>
|    param([AllowNull()]$ErrorRecord, [AllowEmptyString()][AllowNull()][string]$Message, [AllowEmptyString()][string]$ExitReason, [AllowEmptyString()][string]$Service)
|    if ($ExitReason -eq 'settings-error') { return 'settings-error' }
|    if ("$Message" -match '^[a-z0-9][a-z0-9.-]{0,99} refused: ') { return 'guard-refused' }
|    $parts = New-Object System.Collections.Generic.List[string]
|    if ($null -ne $ErrorRecord) { $parts.Add((Get-SIKqlErrorText -ErrorRecord $ErrorRecord)) }
|    if ($Message) { $parts.Add($Message) }
|    $t = ($parts | Where-Object { $_ }) -join ' | '
|    # #702 (1): out of memory ANYWHERE in the text wins over every service / platform word around it (customer B's
|    # "... parameter 'TimeoutSec'. Exception of type 'System.OutOfMemoryException' was thrown" read as platform-timeout)
|    if ((Test-SIOutOfMemoryText $t) -or ($null -ne $ErrorRecord -and (Test-SIOutOfMemoryText $ErrorRecord))) { return 'out-of-memory' }
|    if ([string]::IsNullOrWhiteSpace($t)) { return 'unknown' }
|    # #904: the database is full -- before every service / platform word (its text names SQL and often a timeout)
|    if ((Test-SIDatabaseFullError $t) -or ($null -ne $ErrorRecord -and (Test-SIDatabaseFullError $ErrorRecord))) { return 'database-full' }
|    # 2026-10-29: a temporary Azure SQL error that outlasted SecurityInsight's own retry is TAGGED by the code that retried
|    # it -- its message ends "-- transient-sql" (SI-DataSql.ps1, the pipeline lock); the step's log carries that line, so the
|    # pipeline's report of the step names the platform's class, never a product defect
|    if ($t -match '(?i)--\s*transient-sql\b') { return 'transient-sql' }
|    $svc =Get-SIErrorService -Text $t
|    if (-not $svc -and $Service) { $svc = $Service.ToLowerInvariant() }
|
|    # ---- the run's own configuration ----------------------------------------------------------------------------------
|    if ($t -match '(?i)SecurityInsight Pro: .*settings database|in the settings database are not valid|settings documents could not be prepared') { return 'settings-error' }
|    if ($t -match '(?i)\blicen[cs]e\b.*\b(invalid|not valid|expired|signature verification FAILED|tampered|no entitlement|not readable|could not be read|does not include feature|names no SecurityInsight Pro edition|does not list it)\b|no \.(pimlicense|silicense|aitlicense)|not an AutomateIT licence|signature verification FAILED.*licensing key') { return 'licence-invalid' }
|
|    # ---- identity / sign-in -----------------------------------------------------------------------------------------
|    if ($t -match '(?i)ManagedIdentityCredential|No Managed Identity endpoint|169\.254\.169\.254|IDENTITY_ENDPOINT|\bIMDS\b|MSI endpoint|managed identity.*(unavailable|not available|not found|could not|failed|is not loaded)|identity token helper is not loaded') { return 'mi-unavailable' }
|    if ($t -match "(?i)Login failed for user|Cannot open (server|database) .* requested by the login|\b18456\b|token-identified principal") { return 'sql-login' }
|    if ($t -match "(?i)Cannot (bind|validate) argument (to|on) parameter '(Az)?(ApplicationId|AppId|TenantId|ClientId|CertificateThumbprint|Thumbprint|SubscriptionId|VaultName|WorkspaceId|DcrImmutableId|DceUri|ServicePrincipal\w*)' because it is (an empty string|null)|is not (set|configured)|not found in the configuration|the Pro database is not configured|certificate .* was not found") { return 'config-missing' }
|
|    # ---- ingestion --------------------------------------------------------------------------------------------------
|    if ($t -match '(?i)wrote fewer rows than it carried|fewer rows than (were )?(sent|posted|expected)|short count|rows? (were )?(lost|dropped) (at|during) ingest|accepted \d+ of \d+ rows') { return 'ingest-short-count' }
|
|    # ---- Log Analytics / advanced hunting: the query and the tables -------------------------------------------------
|    # #876: a 'union' leaf says "table expression", a 'where' leaf "table or column expression" -- both: the table is not there
|    if ($t -match "Failed to resolve table (?:or column )?expression named \\?['""]?([A-Za-z0-9_]+)") {
|        $name = $Matches[1]
|        if ($name -match '(?i)_CL$' -or $t -match '(?i)\btable\b.*(could not be found|does not exist)') { return 'table-missing' }
|    }
|    if ($t -match "(?i)\btable\b[^|]{0,120}\b(could not be found|does not exist)|unknown table|PathNotFoundError|not present in this tenant's advanced hunting schema") { return 'table-missing' }
|    foreach ($p in (Get-SIErrorPlatformPrefixesState)) { if ($t -match $p.Pattern) { return $p.Class } }
|    if ($t -match '(?i)Fix syntax errors in your query|Fix semantic errors in your query|SyntaxError|SemanticError|return types are not compatible|\bSEM\d{4}\b|\bSYN\d{4}\b|Expected: .* in query|Failed to resolve (scalar|table or column|table) expression') { return 'kql-query-defect' }
|
|    # ---- throttling -------------------------------------------------------------------------------------------------
|    # ONE decision (Get-SITransientKind): only a real throttling answer is 'throttled'. A Retry-After header alone is not
|    # (a 503 sends one too); SI's own "Microsoft throttled this run" sentence never classifies itself.
|    if ((Get-SITransientKind -Message $t) -eq 'throttled') { return 'throttled' }
|
|    # ---- status codes, by service -----------------------------------------------------------------------------------
|    $code = $null
|    if ($t -match '(?i)\((4\d\d)\)|status code (?:does not indicate success: )?(4\d\d)\b|\b(4\d\d) \((Bad Request|Unauthorized|Forbidden|Not Found|Request Entity Too Large|Conflict)\)|''(BadRequest|Unauthorized|Forbidden|NotFound|RequestEntityTooLarge)''') {
|        $code = @($Matches[1], $Matches[2], $Matches[3], $Matches[5]) | Where-Object { $_ } | Select-Object -First 1
|    }
|    $named = @{ BadRequest = '400'; Unauthorized = '401'; Forbidden = '403'; NotFound = '404'; RequestEntityTooLarge = '413' }
|    if ($code -and $named.ContainsKey($code)) { $code = $named[$code] }
|    $is401 = ($code -eq '401') -or ($t -match '(?i)\bUnauthorized\b|InvalidAuthenticationToken|token is expired|Lifetime validation failed')
|    $is403 = ($code -eq '403') -or ($t -match '(?i)\bForbidden\b|Authorization_RequestDenied|AuthorizationFailed|AuthorizationPermissionMismatch|Insufficient privileges|does not have authorization|does not have (any of )?the required|is not authorized to perform|ForbiddenByRbac|ForbiddenByPolicy|Access denied')
|    if ($svc -eq 'ingest' -and ($code -match '^4\d\d$' -or $is401 -or $is403 -or $t -match '(?i)InvalidTransformOutput|is not associated with DCR|DCE FQDN')) { return 'ingest-4xx' }
|    if ($is401 -or $is403) {
|        switch ($svc) {
|            'graph'    { if ($is401 -and -not $is403) { return 'graph-401' } else { return 'graph-403' } }
|            'defender' { return 'defender-403' }
|            'arm'      { return 'arm-403' }
|            'kv'       { return 'kv-403' }
|            'storage'  { return 'storage-403' }
|            'sql'      { return 'sql-login' }
|            'ai'       { return 'ai-error' }
|            default    { if ($is401 -and -not $is403) { return 'graph-401' } }
|        }
|    }
|
|    # ---- AI ---------------------------------------------------------------------------------------------------------
|    if ($svc -eq 'ai') { return 'ai-error' }
|
|    # ---- the platform -----------------------------------------------------------------------------------------------
|    switch (Get-SITransientKind -Message $t) {
|        'timeout'     { return 'platform-timeout' }
|        'unavailable' { return 'platform-5xx' }
|    }
|    'unknown'
|}
'@ }
$__siSupportFiles['engine/_shared/SI-KqlError.ps1'] = @{ Sha256 = 'ee8dfba0c796cb9c3a24f592a058e3b1223b4edff9a71df30d7bd65465d14221'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- what a failed Log Analytics query actually said (#221).
|
|    WHY. Az.OperationalInsights throws ErrorResponseException whose MESSAGE is only
|    "Operation returned an invalid status code 'BadRequest'". The reason -- e.g. SEM0100 "Failed to resolve table or
|    column expression named 'SI_PublicIP_Profile_CL'" -- is in the response body (Exception.Response.Content /
|    Exception.Body). Measured 2026-10-03 on 3.4.0 (container) and 3.4.1 (the development machine), PS 5.1 and pwsh 7 alike.
|    Readers that classified on the message therefore never recognised a MISSING table: on a fresh install, where a
|    profile or Risk Analysis table does not exist yet, correlation, trend and the close-loop failed outright.
|
|    A missing table is the ONLY error a reader may treat as "no data here yet". Everything else still fails loudly --
|    a throttle or timeout must never pass as an empty table (#132).
|
|    PS 5.1 safe: no ?. / ??.
|#>
|
|function Get-SIKqlErrorText {
|    <# PURE. Every text a Log Analytics query failure carries: the message, the response body, the typed body, inner
|       exceptions and ErrorDetails -- joined, so a caller can classify on what the service really said. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $parts = New-Object System.Collections.Generic.List[string]
|    $ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
|    if ($ErrorRecord -is [System.Management.Automation.ErrorRecord] -and $ErrorRecord.ErrorDetails -and $ErrorRecord.ErrorDetails.Message) {
|        $parts.Add([string]$ErrorRecord.ErrorDetails.Message)
|    }
|    $depth = 0
|    while ($ex -and $depth -lt 5) {
|        $parts.Add([string]$ex.Message)
|        if ($ex.PSObject.Properties['Response'] -and $ex.Response) {
|            $c = $null
|            if ($ex.Response.PSObject.Properties['Content']) { $c = $ex.Response.Content }
|            if ($c) { $parts.Add([string]$c) }
|        }
|        if ($ex.PSObject.Properties['Body'] -and $ex.Body) {
|            try { $parts.Add((ConvertTo-Json -InputObject $ex.Body -Depth 8 -Compress)) } catch { $parts.Add([string]$ex.Body) }
|        }
|        $ex = $ex.InnerException
|        $depth++
|    }
|    return (($parts | Where-Object { $_ }) -join ' | ')
|}
|
|function Get-SIKqlErrorSummary {
|    <# PURE. ONE log-ready line: the exception message plus the service's own error code(s) and the innermost
|       message, e.g. "Operation returned an invalid status code 'BadRequest' -- SemanticError/SEM0100: 'summarize'
|       operator: Failed to resolve scalar expression named 'AssetName'". Without it a query defect logs only
|       "BadRequest", which says nothing about what to fix. The bare message is kept at the front so classifiers that
|       match on it (BadRequest, TaskCanceledException, 502 ...) see exactly what they saw before. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
|    $base = if ($ex -and $ex.PSObject.Properties['Message']) { [string]$ex.Message } else { [string]$ex }
|    $text = Get-SIKqlErrorText -ErrorRecord $ErrorRecord
|    if (-not $text) { return $base }
|    # The Log Analytics body nests the reason: error -> innererror (SemanticError / SyntaxError) -> innererror
|    # (SEM0100 ...). Collect the innererror chain of the first body found; the deepest message is the useful one.
|    $rx = '"innererror"\s*:\s*\{\s*"code"\s*:\s*"([^"]*)"\s*,\s*"message"\s*:\s*"((?:[^"\\]|\\.)*)"'
|    $ms = [regex]::Matches($text, $rx)
|    if ($ms.Count -eq 0) { return $base }
|    $codes = New-Object System.Collections.Generic.List[string]
|    $msg = ''
|    foreach ($m in $ms) {
|        $c = $m.Groups[1].Value
|        if ($codes.Contains($c)) { break }   # a second copy of the same body (typed body / ErrorDetails) starts here
|        $codes.Add($c)
|        $msg = $m.Groups[2].Value
|    }
|    try { $msg = [regex]::Unescape($msg) } catch { }
|    $detail = ('{0}: {1}' -f ($codes -join '/'), $msg)
|    if ($base -and $base.Contains($msg)) { return $base }
|    if (-not $base) { return $detail }
|    return ('{0} -- {1}' -f $base, $detail)
|}
|
|function Test-SIKqlTableMissing {
|    <# PURE. True only when the failure says THIS table does not exist in the workspace. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord, [Parameter(Mandatory)][string]$TableName)
|    $t = Get-SIKqlErrorText -ErrorRecord $ErrorRecord
|    if (-not $t) { return $false }
|    $name = [regex]::Escape($TableName)
|    # #876: a 'union' leaf says "table expression", a 'where' leaf "table or column expression" -- both: the table is not there
|    if ($t -match ("Failed to resolve table (?:or column )?expression named \\?['""]?{0}" -f $name)) { return $true }
|    if ($t -match $name -and $t -match '(?i)SEM0100|could not be found|does not exist|unknown table') { return $true }
|    return $false
|}
'@ }
$__siSupportFiles['auth/SI-ManagedIdentity.ps1'] = @{ Sha256 = '8198e8e891fb59de6e58fe9f8b08fe7f3f838586096d36758b85aa0e118f6673'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- sign in with a MANAGED IDENTITY: a container job's (#209), an Azure VM's or an Azure Arc
|    server's (#222).
|
|    WHY. An engine container could only sign in with an SPN client SECRET. Internal installs are certificate
|    only, and Pro is container only, so a certificate-only customer could not run Pro at all. PIM4EntraPS's
|    containers sign in as the job's managed identity; this copies that (PIM: Get-PimManagedIdentityToken).
|    #222 (operator 2026-10-03): the managed identity is the DEFAULT everywhere; an SPN stays supported.
|
|    THE ONE SWITCH. A run uses the managed identity when $global:SI_UseManagedIdentity = $true.
|        $global:SI_UAMI_ClientId = '<client id>'   optional: a USER-assigned identity; empty = the host's
|                                                    system-assigned identity
|    Who sets it: the container entry points (when the job has an identity endpoint), and on a VM the sign-in
|    decision in the config loader (auth/SI-AuthMethod.ps1). When it is off, every function below either is
|    never called or returns "not mine" -- the secret and certificate paths are exactly what they were.
|    The host decides the endpoint (Get-SIManagedIdentityHost): container IDENTITY_ENDPOINT + IDENTITY_HEADER;
|    Azure Arc IDENTITY_ENDPOINT + IMDS_ENDPOINT (401 challenge file); otherwise the Azure VM endpoint.
|
|    Log ingestion keeps its existing switch ($global:SI_PreferUami + SI_UAMI_ClientId -> -UseManagedIdentity on
|    SI's REST ingestion, which mints the token here); the container sets that from the same decision. No second
|    identity switch.
|
|    PS 5.1 safe: no ?. / ??.
|#>
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot '../engine/_shared/SI-AzRest.ps1') }
|
|$__siFindCert = Join-Path $PSScriptRoot 'Find-SICertificate.ps1'
|if ((Test-Path -LiteralPath $__siFindCert) -and -not (Get-Command Get-SICertificateFromStore -ErrorAction SilentlyContinue)) { . $__siFindCert }
|
|if (-not (Get-Variable -Name SIManagedIdentityTokenCache -Scope Script -ErrorAction SilentlyContinue)) {
|    $script:SIManagedIdentityTokenCache = @{}   # '<clientId>|<resource>' -> @{ Token; ExpiresAt }
|}
|
|function Test-SIUseManagedIdentity {
|    <# THE switch: this run signs in as a managed identity (a container job's, an Azure VM's or an Azure Arc
|       server's -- #222). The client id is optional: empty = the host's SYSTEM-assigned identity. #>
|    return [bool]$global:SI_UseManagedIdentity
|}
|
|function Get-SIManagedIdentityHost {
|    <#
|        PURE (reads env only). Which managed-identity endpoint this host has (#222):
|          Container -- Azure Container Apps / App Service: IDENTITY_ENDPOINT + IDENTITY_HEADER
|          Arc       -- an Azure Arc-enabled server: IDENTITY_ENDPOINT + IMDS_ENDPOINT, no IDENTITY_HEADER (the Arc
|                       agent sets both machine-wide); the token needs a challenge-file handshake
|          AzureVm   -- an Azure VM (and anything else): the instance metadata endpoint 169.254.169.254
|    #>
|    param([scriptblock]$GetEnv)
|    if (-not $GetEnv) { $GetEnv = { param($n) [Environment]::GetEnvironmentVariable($n) } }
|    $ep = [string](& $GetEnv 'IDENTITY_ENDPOINT'); $hd = [string](& $GetEnv 'IDENTITY_HEADER'); $imds = [string](& $GetEnv 'IMDS_ENDPOINT')
|    if ($ep -and $hd) { return 'Container' }
|    if ($ep -and $imds) { return 'Arc' }
|    return 'AzureVm'
|}
|
|function Get-SIManagedIdentityToken {
|    <#
|        A token for -Resource as this host's managed identity (#209 container, #222 Azure VM + Azure Arc):
|          Container -- IDENTITY_ENDPOINT + X-IDENTITY-HEADER, api-version 2019-08-01, client_id when known
|          AzureVm   -- http://169.254.169.254/metadata/identity/oauth2/token, Metadata: true, client_id when known
|          Arc       -- IDENTITY_ENDPOINT (api-version 2020-06-01, Metadata: true): the first call answers 401 with
|                       'WWW-Authenticate: Basic realm=<file>'; the file's content is the secret for the second call.
|                       Reading it needs local Administrators or the 'Hybrid agent extension applications' group. Arc
|                       has the SYSTEM-assigned identity only, so no client_id.
|
|        TRAP: THE client_id IS NOT OPTIONAL IN PRACTICE for a user-assigned identity. PIM4EntraPS measured it: with a
|        user-assigned identity only, the endpoint has nothing to default to and the failure surfaces far away as
|        "Login failed" / 401. So it is always sent when known.
|
|        Cached per identity + resource until 5 minutes before the token's own expiry. -Invoke is a test seam:
|        { param($Uri, $Headers) } returning the endpoint's response (Arc: the @{Status;Body;WwwAuthenticate} shape).
|        -ReadFile is a test seam for the Arc challenge file.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Resource,
|        [string]$ClientId,
|        [switch]$ForceRefresh,
|        [scriptblock]$Invoke,
|        [scriptblock]$ReadFile
|    )
|    # A guided install's own sign-in wins (live 2026-10-06, an AzContext install on an Azure VM got the VM's IMDS token for
|    # SQL): while $global:SI_InstallTokenProvider is set, the token comes from it and NO identity endpoint is called.
|    $installProvider = Get-Variable -Scope Global -Name SI_InstallTokenProvider -ValueOnly -ErrorAction Ignore
|    # Re-entry = the install's sign-in itself IS this host's managed identity (sign-in mode ManagedIdentity): then, and only
|    # then, the identity endpoint below answers.
|    if (($installProvider -is [scriptblock]) -and -not $global:SI_InstallTokenProviderBusy) {
|        $global:SI_InstallTokenProviderBusy = $true
|        try { $pt = [string](& $installProvider $Resource) } finally { $global:SI_InstallTokenProviderBusy = $false }
|        if ([string]::IsNullOrWhiteSpace($pt)) { throw ("the install's sign-in returned no token for '{0}'." -f $Resource) }
|        return $pt
|    }
|    # SELF-CONTAINED on purpose: it is published to the global scope and may run where this file's other functions are
|    # not visible. The host rule is Get-SIManagedIdentityHost's, repeated here.
|    $endpoint = [Environment]::GetEnvironmentVariable('IDENTITY_ENDPOINT')
|    $header   = [Environment]::GetEnvironmentVariable('IDENTITY_HEADER')
|    $imdsEp   = [Environment]::GetEnvironmentVariable('IMDS_ENDPOINT')
|    $hostKind = if ($endpoint -and $header) { 'Container' } elseif ($endpoint -and $imdsEp) { 'Arc' } else { 'AzureVm' }
|    $arcGet = {
|        param([string]$U, [hashtable]$H)
|        $req = [System.Net.HttpWebRequest]::Create($U)
|        $req.Method = 'GET'; $req.Timeout = 60000
|        foreach ($k in $H.Keys) { if ($k -eq 'Authorization') { $req.Headers['Authorization'] = [string]$H[$k] } else { $req.Headers.Add($k, [string]$H[$k]) } }
|        try { $r = $req.GetResponse() }
|        catch [System.Net.WebException] { $r = $_.Exception.Response; if (-not $r) { throw } }
|        try {
|            $sr = New-Object System.IO.StreamReader($r.GetResponseStream()); $b = $sr.ReadToEnd(); $sr.Close()
|            [pscustomobject]@{ Status = [int]$r.StatusCode; Body = $b; WwwAuthenticate = [string]$r.Headers['WWW-Authenticate'] }
|        } finally { $r.Close() }
|    }
|    if ([string]::IsNullOrWhiteSpace($ClientId)) { $ClientId = [string]$global:SI_UAMI_ClientId }
|    # The cache is created HERE, not only when this file loads: when this function runs from another scope, `$script:` is
|    # that scope and the file-level cache does not exist.
|    # Measured live 2026-10-02 (first container run on the identity): "You cannot call a method on a null-valued
|    # expression" on every token, and every Log Analytics post failed.
|    if ($null -eq $script:SIManagedIdentityTokenCache) { $script:SIManagedIdentityTokenCache = @{} }
|    $res = ($Resource -replace '/\.default$', '')
|    $key = '{0}|{1}' -f $ClientId, $res
|    if (-not $ForceRefresh -and $script:SIManagedIdentityTokenCache.ContainsKey($key)) {
|        $c = $script:SIManagedIdentityTokenCache[$key]
|        if ($c.ExpiresAt -gt [datetime]::UtcNow) { return $c.Token }
|    }
|
|    $resp = $null
|    switch ($hostKind) {
|        'Container' {
|            $uri = '{0}?resource={1}&api-version=2019-08-01' -f $endpoint, [uri]::EscapeDataString($res)
|            if (-not [string]::IsNullOrWhiteSpace($ClientId)) { $uri += '&client_id=' + [uri]::EscapeDataString($ClientId) }
|            $headers = @{ 'X-IDENTITY-HEADER' = $header }
|            $resp = if ($Invoke) { & $Invoke $uri $headers }
|                    else { Invoke-RestMethod -Method Get -Uri $uri -Headers $headers -TimeoutSec 60 }
|        }
|        'AzureVm' {
|            $uri = 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource={0}' -f [uri]::EscapeDataString($res)
|            if (-not [string]::IsNullOrWhiteSpace($ClientId)) { $uri += '&client_id=' + [uri]::EscapeDataString($ClientId) }
|            $headers = @{ 'Metadata' = 'true' }
|            $resp = if ($Invoke) { & $Invoke $uri $headers }
|                    else { Invoke-RestMethod -Method Get -Uri $uri -Headers $headers -TimeoutSec 60 }
|        }
|        'Arc' {
|            $uri = '{0}?api-version=2020-06-01&resource={1}' -f $endpoint, [uri]::EscapeDataString($res)
|            $first = if ($Invoke) { & $Invoke $uri @{ 'Metadata' = 'true' } } else { & $arcGet $uri @{ 'Metadata' = 'true' } }
|            if ([int]$first.Status -ne 401 -or [string]$first.WwwAuthenticate -notmatch '(?i)realm=(.+)$') {
|                throw ("managed identity (Azure Arc): expected a 401 challenge from {0}, got {1}. Is the Arc agent running?" -f $endpoint, $first.Status)
|            }
|            $keyFile = $Matches[1].Trim().Trim('"')
|            $secret = $null
|            try { $secret = if ($ReadFile) { & $ReadFile $keyFile } else { [System.IO.File]::ReadAllText($keyFile) } }
|            catch { throw ("managed identity (Azure Arc): cannot read the challenge file {0} -- the run must be a local Administrator or in the 'Hybrid agent extension applications' group. {1}" -f $keyFile, $_.Exception.Message) }
|            $second = if ($Invoke) { & $Invoke $uri @{ 'Metadata' = 'true'; 'Authorization' = ('Basic ' + $secret) } }
|                      else { & $arcGet $uri @{ 'Metadata' = 'true'; 'Authorization' = ('Basic ' + $secret) } }
|            if ([int]$second.Status -ne 200) { throw ("managed identity (Azure Arc): the identity endpoint refused the token request ({0})." -f $second.Status) }
|            $resp = $second.Body | ConvertFrom-Json
|        }
|    }
|    $token = [string]$resp.access_token
|    if ([string]::IsNullOrWhiteSpace($token)) {
|        throw ("managed identity ({2}): the identity endpoint returned no token for '{0}' (client id {1}). Is that identity assigned to this host / job?" -f $res, $ClientId, $hostKind)
|    }
|
|    $expiresAt = [datetime]::UtcNow.AddMinutes(50)
|    $epoch = 0L
|    if ([long]::TryParse([string]$resp.expires_on, [ref]$epoch) -and $epoch -gt 0) {
|        $expiresAt = [DateTimeOffset]::FromUnixTimeSeconds($epoch).UtcDateTime.AddMinutes(-5)
|    } else {
|        $secs = 0
|        if ([int]::TryParse([string]$resp.expires_in, [ref]$secs) -and $secs -gt 600) { $expiresAt = [datetime]::UtcNow.AddSeconds($secs - 300) }
|    }
|    $script:SIManagedIdentityTokenCache[$key] = @{ Token = $token; ExpiresAt = $expiresAt }
|    # #232 -- the licence is checked against the tenant the identity REALLY lives in. A managed identity's token always
|    # comes from its home tenant, whatever the configuration claims, so its 'tid' claim is the proof; a configured tenant
|    # id is not (a copied licence plus an edited config would otherwise pass). Recorded from every real token.
|    try {
|        $seg = $token.Split('.')
|        if ($seg.Count -ge 2) {
|            $p = $seg[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }
|            $tid = [string](([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p))) | ConvertFrom-Json).tid
|            if ($tid -match '^[0-9a-fA-F-]{36}$') { $global:SI_IdentityTokenTenantId = $tid.ToLowerInvariant() }
|        }
|    } catch { }
|    try { [System.Console]::Out.WriteLine(("  [mi] token for {0} via the {2} identity endpoint (len {1})" -f $res, $token.Length, $hostKind)) } catch { }
|    return $token
|}
|
|function Get-SIAccessToken {
|    <#
|        "A token for resource X as the identity this run uses." The managed identity when the switch is on;
|        otherwise the run's own sign-in (Get-SIAzAccessToken, over REST).
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [switch]$ForceRefresh)
|    if (Test-SIUseManagedIdentity) { return (Get-SIManagedIdentityToken -Resource $Resource -ForceRefresh:$ForceRefresh) }
|    $t = Get-SIAzAccessToken -ResourceUrl $Resource -ErrorAction Stop
|    if ($t.Token -is [System.Security.SecureString]) { return [System.Net.NetworkCredential]::new('', $t.Token).Password }
|    return [string]$t.Token
|}
'@ }
$__siSupportFiles['setup/_shared/SI-SetupSignIn.ps1'] = @{ Sha256 = 'f679aeea5410c99712147634239b38093e6d3973996f57bd67db46f4f947596c'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight SETUP -- signing in to Azure with NO PowerShell modules (native REST and .NET only).
|
|    WHO SIGNS IN, AND HOW
|      A person (the guided install, the wizard, Setup-SecurityInsight, Bootstrap-*, Grant-*, Validate-* ...):
|        * Azure Cloud Shell  -- the Cloud Shell token endpoint ($env:MSI_ENDPOINT, else $env:IDENTITY_ENDPOINT). It hands
|                                out tokens for the person who opened Cloud Shell, per resource, with no prompt.
|        * a workstation      -- OAuth 2.0 authorization code + PKCE in the person's own browser, answered on a loopback
|                                listener (System.Net.HttpListener on http://localhost:<free port>/). The client is the
|                                public Azure PowerShell client, so the same consent and the same Microsoft Graph rights
|                                (Directory.AccessAsUser.All) setup always had. NO device code: it is blocked by
|                                Conditional Access in many tenants and is deliberately not offered.
|        Tokens for the other resources (Graph, Key Vault, Storage, Log Analytics, SQL ...) come from the refresh token
|        (browser) or the Cloud Shell endpoint, on first use. EXCEPT Exchange Online (https://outlook.office365.com): its
|        admin API accepts only a token of the Exchange Online PowerShell client (Get-SISignInExchangeClientId), so the first
|        Exchange token is one more browser sign-in with that client (same flow, the account pre-filled), then its own
|        refresh token. Everything is kept IN MEMORY in this PowerShell process --
|        nothing is written to disk.
|      An app (unattended setup, CI): a certificate or a client secret -- recorded by Connect-SIAzAccount (REST), tokens
|        minted by engine/_shared (client assertion / client credentials). A managed identity likewise.
|
|    HOW THE REST LAYER USES IT
|      engine/_shared/SI-AzRest.ps1 asks Get-SIAzureToken for every token. setup/_shared/SI-SetupAzure.ps1 loads that file
|      and then defines Get-SIAzureToken once more, here: a USER sign-in is answered from this file, anything else exactly
|      as the engine does. So Invoke-SIArm, the *-SIAz* REST twins, Key Vault, Graph and storage all run as the signed-in
|      person without knowing it.
|
|    TEST SEAMS: every HTTP call goes through Invoke-SIAzRestHttp (engine); the browser through Open-SISignInBrowser; the
|    loopback wait through Wait-SILoopbackAuthCode. Pure helpers (PKCE pair, authorize URL, redirect parsing) are public.
|
|    PS 5.1 safe (no ?. / ??), pwsh 7 on Windows, Linux (Cloud Shell) and macOS.
|#>
|
|# NO Set-StrictMode here -- it leaks into the caller's scope.
|
|
|function Get-SISignInClientId {
|    <# The public client the browser sign-in uses: $global:SI_SetupSignInClientId (an organisation's own public app
|       registration with an http://localhost redirect) when set, else the Azure PowerShell client. #>
|    $c = "$(Get-Variable -Scope Global -Name SI_SetupSignInClientId -ValueOnly -ErrorAction Ignore)"
|    if ($c.Trim()) { return $c.Trim() }
|    return '1950a258-227b-4e31-a9cf-717495945fc2'
|}
|
|function Get-SISignInExchangeClientId {
|    <# The public client the Exchange Online admin API (https://outlook.office365.com/adminapi/...) is signed in with:
|       "Microsoft Exchange REST API Based Powershell", the client the Exchange Online PowerShell V3 module itself uses
|       (PIM4EntraPS does the same). A delegated token for Exchange must carry Exchange.Manage; the Azure PowerShell client
|       is not consented for it, so Exchange answered its token with 401 Unauthorized (customer ticket 2026-10-15).
|       $global:SI_SetupExchangeClientId overrides it (an organisation's own public app with Exchange.Manage). #>
|    $c = "$(Get-Variable -Scope Global -Name SI_SetupExchangeClientId -ValueOnly -ErrorAction Ignore)"
|    if ($c.Trim()) { return $c.Trim() }
|    return 'fb78d390-0c51-40cd-8e17-fdbfab77341b'
|}
|
|function Test-SISignInExchangeResource {
|    <# PURE. True for the Exchange Online resource (its admin API takes only a token of the Exchange client). #>
|    param([string]$Resource)
|    $r = ("$Resource" -replace '/\.default$', '').TrimEnd('/').ToLowerInvariant()
|    return ($r -eq 'https://outlook.office365.com' -or $r -eq 'https://outlook.office.com')
|}
|
|function Get-SISignInState {
|    <# The in-memory sign-in of this process: the user session (method, tenant, account, refresh token) and its tokens. #>
|    if (-not ((Get-Variable -Scope Global -Name SI_SetupSignInState -ValueOnly -ErrorAction Ignore) -is [hashtable])) {
|        $global:SI_SetupSignInState = @{ Session = $null; Tokens = @{} }
|    }
|    return $global:SI_SetupSignInState
|}
|
|function Test-SICloudShell {
|    <# True in Azure Cloud Shell: the Cloud Shell markers AND a token endpoint. #>
|    $marker = ([string]$env:AZUREPS_HOST_ENVIRONMENT) -like 'cloud-shell*' -or [bool]$env:ACC_CLOUD -or [bool]$env:ACC_TERM_ID
|    return ($marker -and [bool](Get-SICloudShellEndpoint))
|}
|
|function Get-SICloudShellEndpoint {
|    $e = [string]$env:MSI_ENDPOINT
|    if (-not $e.Trim()) { $e = [string]$env:IDENTITY_ENDPOINT }
|    return $e.Trim()
|}
|
|# ---------------------------------------------------------------------------------------------------------------
|# PURE helpers: PKCE, state, the authorize URL, the redirect, token claims
|# ---------------------------------------------------------------------------------------------------------------
|function ConvertTo-SIBase64Url {
|    param([Parameter(Mandatory)][byte[]]$Bytes)
|    return ([Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_'))
|}
|
|function New-SIRandomBase64Url {
|    param([int]$ByteCount = 32)
|    $b = New-Object byte[] $ByteCount
|    $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
|    try { $rng.GetBytes($b) } finally { $rng.Dispose() }
|    return (ConvertTo-SIBase64Url -Bytes $b)
|}
|
|function Get-SIPkceChallenge {
|    <# RFC 7636 S256: BASE64URL(SHA256(ASCII(verifier))). #>
|    param([Parameter(Mandatory)][string]$Verifier)
|    $sha = [System.Security.Cryptography.SHA256]::Create()
|    try { $h = $sha.ComputeHash([System.Text.Encoding]::ASCII.GetBytes($Verifier)) } finally { $sha.Dispose() }
|    return (ConvertTo-SIBase64Url -Bytes $h)
|}
|
|function New-SIPkcePair {
|    <# A fresh verifier (43 chars from 32 random bytes, inside RFC 7636's 43..128 unreserved set) and its S256 challenge. #>
|    $v = New-SIRandomBase64Url -ByteCount 32
|    return [pscustomobject]@{ Verifier = $v; Challenge = (Get-SIPkceChallenge -Verifier $v); Method = 'S256' }
|}
|
|function Get-SISignInScope {
|    <# The v2 scope of a resource: 'https://graph.microsoft.com/' -> 'https://graph.microsoft.com/.default'. #>
|    param([Parameter(Mandatory)][string]$Resource)
|    $r = ($Resource -replace '/\.default$', '').TrimEnd('/')
|    return ($r + '/.default')
|}
|
|function Get-SIAuthorizeUrl {
|    <# The Microsoft Entra authorize URL for the code + PKCE flow. #>
|    param(
|        [string]$TenantId,
|        [Parameter(Mandatory)][string]$ClientId,
|        [Parameter(Mandatory)][string]$RedirectUri,
|        [Parameter(Mandatory)][string]$Scope,
|        [Parameter(Mandatory)][string]$CodeChallenge,
|        [Parameter(Mandatory)][string]$State,
|        [string]$LoginHint,
|        [string]$Prompt = 'select_account'
|    )
|    $t = if ([string]::IsNullOrWhiteSpace($TenantId)) { 'organizations' } else { $TenantId.Trim() }
|    $q = [ordered]@{
|        client_id             = $ClientId
|        response_type         = 'code'
|        redirect_uri          = $RedirectUri
|        response_mode         = 'query'
|        scope                 = $Scope
|        state                 = $State
|        code_challenge        = $CodeChallenge
|        code_challenge_method = 'S256'
|    }
|    if ($Prompt) { $q['prompt'] = $Prompt }
|    if ($LoginHint) { $q['login_hint'] = $LoginHint }
|    $pairs = foreach ($k in $q.Keys) { '{0}={1}' -f $k, [uri]::EscapeDataString([string]$q[$k]) }
|    return ('https://login.microsoftonline.com/{0}/oauth2/v2.0/authorize?{1}' -f [uri]::EscapeDataString($t), ($pairs -join '&'))
|}
|
|function ConvertFrom-SIQueryString {
|    <# '?a=1&b=x%20y' -> @{ a = '1'; b = 'x y' } (case-insensitive keys). #>
|    param([string]$Query)
|    $h = New-Object 'System.Collections.Hashtable' ([System.StringComparer]::OrdinalIgnoreCase)
|    $q = ([string]$Query).TrimStart('?')
|    foreach ($p in ($q -split '&')) {
|        if (-not $p) { continue }
|        $i = $p.IndexOf('=')
|        $k = if ($i -ge 0) { $p.Substring(0, $i) } else { $p }
|        $v = if ($i -ge 0) { $p.Substring($i + 1) } else { '' }
|        $h[[uri]::UnescapeDataString($k.Replace('+', ' '))] = [uri]::UnescapeDataString($v.Replace('+', ' '))
|    }
|    return $h
|}
|
|function Resolve-SIAuthRedirect {
|    <#
|        The browser's redirect back to the loopback listener -> the authorization code. Throws in customer language when
|        Entra returned an error, when the state does not match (a response this sign-in did not ask for), or when no
|        code came back.
|    #>
|    param([Parameter(Mandatory)][AllowEmptyString()][string]$Query, [Parameter(Mandatory)][string]$ExpectedState)
|    $q = ConvertFrom-SIQueryString -Query $Query
|    if ($q['error']) {
|        $d = [string]$q['error_description']
|        throw ("The Microsoft sign-in did not complete: {0}{1}" -f $q['error'], $(if ($d) { ' -- ' + $d } else { '' }))
|    }
|    if ([string]$q['state'] -ne $ExpectedState) {
|        throw 'The sign-in answer did not belong to this sign-in (the state value does not match). Nothing was signed in; run the same command again.'
|    }
|    if (-not $q['code']) { throw 'The sign-in answer carried no authorization code. Run the same command again.' }
|    return [string]$q['code']
|}
|
|function ConvertFrom-SISignInJwt {
|    <# The claims of a JWT (no signature check -- only read to learn the tenant, the account and the expiry). #>
|    param([string]$Token)
|    $parts = ([string]$Token) -split '\.'
|    if ($parts.Count -lt 2) { return $null }
|    $p = $parts[1].Replace('-', '+').Replace('_', '/')
|    switch ($p.Length % 4) { 2 { $p += '==' } 3 { $p += '=' } }
|    try { return ([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json) } catch { return $null }
|}
|
|function Get-SISignInAccountName {
|    param($Claims)
|    if (-not $Claims) { return $null }
|    foreach ($n in 'upn', 'preferred_username', 'unique_name', 'email', 'oid') {
|        if ($Claims.PSObject.Properties[$n] -and [string]$Claims.$n) { return [string]$Claims.$n }
|    }
|    return $null
|}
|
|function Get-SITokenExpiry {
|    <# When a token response expires (5 minutes early): expires_in (seconds) or expires_on (unix seconds / a date). #>
|    param($Response)
|    $now = [datetime]::UtcNow
|    $s = 0
|    if ($Response.PSObject.Properties['expires_in'] -and [int]::TryParse([string]$Response.expires_in, [ref]$s) -and $s -gt 0) {
|        return $now.AddSeconds([Math]::Max(60, $s - 300))
|    }
|    if ($Response.PSObject.Properties['expires_on']) {
|        $l = 0L
|        if ([long]::TryParse([string]$Response.expires_on, [ref]$l) -and $l -gt 0) {
|            return ([DateTimeOffset]::FromUnixTimeSeconds($l).UtcDateTime.AddMinutes(-5))
|        }
|        $d = [datetime]::MinValue
|        if ([datetime]::TryParse([string]$Response.expires_on, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::AdjustToUniversal, [ref]$d)) {
|            return $d.AddMinutes(-5)
|        }
|    }
|    return $now.AddMinutes(30)
|}
|
|# ---------------------------------------------------------------------------------------------------------------
|# HANDED-OVER TOKENS (#876, owner 2026-10-21 "test trial with support app today"): Invardia's bootstrap may hand the
|# install the access tokens it already holds, in $env:SI_HANDOFF_TOKENS -- the same shape as PIM_HANDOFF_TOKENS:
|#   { "https://management.azure.com/": { "access_token": "...", "expires_on": <unix seconds> },
|#     "https://graph.microsoft.com/": {...}, "https://database.windows.net/": {...} }
|# With them the install signs in to NOTHING itself: no browser, no Cloud Shell endpoint, no app sign-in. The tokens may be
|# a person's (delegated) or an application's (the Invardia Support app: idtyp app, no scp) -- the claims say which, and an
|# application's object id (oid) IS its service principal's. Every token must be for the SAME tenant (and for the install's
|# tenant when one is named): one for another tenant refuses the whole hand-over. Read ONCE, kept in memory only
|# ($global:SI_SetupHandoff), and the variable is removed from the environment so no later process inherits it. No refresh
|# token crosses over, so a token cannot be renewed: when one is about to run out the install STOPS with one plain line
|# and resumes from that step with a fresh hand-over. An Invardia Support session open in the same shell wins over the
|# hand-over (its calls are recorded in the customer's audit log and its tokens are renewed by the session).
|# ---------------------------------------------------------------------------------------------------------------
|$script:SIHandoffMinMinutes = 2
|
|function Get-SIHandoffResourceKey {
|    <# PURE. The comparison key of a token audience: 'https://graph.microsoft.com' and '.../' and '.../.default' are one. #>
|    param([string]$Resource)
|    return ((("$Resource".Trim()) -replace '/\.default$', '').TrimEnd('/') + '/').ToLowerInvariant()
|}
|
|function Get-SIHandoffExpiredText {
|    <# PURE. The one line said when a handed-over token runs out (the install resumes from the step it stopped at). #>
|    param([string]$Resource)
|    $what = if ("$Resource".Trim()) { ' (for {0})' -f (Get-SIHandoffResourceKey $Resource).TrimEnd('/') } else { '' }
|    'The hand-over sign-in{0} has expired -- restart the install with a fresh code from the installation page (the install resumes where it stopped).' -f $what
|}
|
|function Import-SIHandoffTokens {
|    <#
|        PURE given -Json and -NowUtc. Reads the bootstrap's hand-over JSON. Returns
|          @{ Present; Ok; Reason; TenantId; IsApp; ObjectId; AppId; Account; Tokens = @{ <resource key> = @{ Token; ExpiresAt } } }
|        Present = something was handed over. Ok = it can be used (at least an Azure Resource Manager token, every token for
|        one tenant -- -TenantId when given -- and every token of one kind: all a person's or all one application's).
|        Reason (when not Ok) never contains token text. ExpiresAt = the earlier of expires_on and the token's own exp.
|    #>
|    param([AllowEmptyString()][string]$Json, [string]$TenantId, [datetime]$NowUtc = [datetime]::UtcNow)
|    $out = @{ Present = $false; Ok = $false; Reason = ''; TenantId = ''; IsApp = $false; ObjectId = ''; AppId = ''; Account = ''; Tokens = @{} }
|    if (-not "$Json".Trim()) { return $out }
|    $out.Present = $true
|    $o = $null
|    try { $o = "$Json" | ConvertFrom-Json } catch { $out.Reason = 'the hand-over could not be read (it is not JSON)'; return $out }
|    $tids = @(); $kinds = @(); $oids = @()
|    foreach ($p in @($o.PSObject.Properties)) {
|        $v = $p.Value; $tok = ''; $exp = $null
|        if ($v -is [string]) { $tok = $v }
|        elseif ($null -ne $v -and $v.PSObject.Properties['access_token']) { $tok = [string]$v.access_token; if ($v.PSObject.Properties['expires_on']) { $exp = $v.expires_on } }
|        if (-not $tok.Trim()) { continue }
|        $c = ConvertFrom-SISignInJwt $tok
|        if (-not $c -or -not $c.PSObject.Properties['tid'] -or -not [string]$c.tid) { $out.Reason = ('the token handed over for {0} cannot be read (no tenant in it)' -f $p.Name); return $out }
|        $tid = ([string]$c.tid).Trim().ToLowerInvariant()
|        if ("$TenantId".Trim() -and $tid -ne "$TenantId".Trim().ToLowerInvariant()) {
|            $out.Reason = ('the token handed over for {0} is for tenant {1}, not this installation''s tenant {2}' -f $p.Name, $tid, "$TenantId".Trim()); return $out
|        }
|        $isApp = ([string]$(if ($c.PSObject.Properties['idtyp']) { $c.idtyp } else { '' }) -eq 'app') -or -not ($c.PSObject.Properties['scp'] -and [string]$c.scp)
|        # the expiry: the earlier of what the bootstrap says and the token's own exp claim
|        $ends = @()
|        $l = 0L
|        if ($null -ne $exp -and [long]::TryParse([string]$exp, [ref]$l) -and $l -gt 0) { $ends += [DateTimeOffset]::FromUnixTimeSeconds($l).UtcDateTime }
|        if ($c.PSObject.Properties['exp'] -and [long]::TryParse([string]$c.exp, [ref]$l) -and $l -gt 0) { $ends += [DateTimeOffset]::FromUnixTimeSeconds($l).UtcDateTime }
|        if (-not $ends.Count) { $out.Reason = ('the token handed over for {0} carries no expiry' -f $p.Name); return $out }
|        $out.Tokens[(Get-SIHandoffResourceKey $p.Name)] = @{ Token = $tok; ExpiresAt = (@($ends | Sort-Object) | Select-Object -First 1) }
|        $tids += $tid; $kinds += $isApp; $oids += ([string]$(if ($c.PSObject.Properties['oid']) { $c.oid } else { '' })).ToLowerInvariant()
|        if (-not $out.AppId -and $c.PSObject.Properties['appid']) { $out.AppId = [string]$c.appid }
|        if (-not $out.AppId -and $c.PSObject.Properties['azp']) { $out.AppId = [string]$c.azp }
|        if (-not $out.Account -and -not $isApp) { $out.Account = [string](Get-SISignInAccountName $c) }
|    }
|    if (-not $out.Tokens.Count) { $out.Reason = 'the hand-over holds no token'; return $out }
|    if (@($tids | Select-Object -Unique).Count -gt 1) { $out.Reason = ('the tokens handed over are for different tenants ({0})' -f ((@($tids | Select-Object -Unique)) -join ', ')); $out.Tokens = @{}; return $out }
|    if (@($kinds | Select-Object -Unique).Count -gt 1 -or @($oids | Where-Object { $_ } | Select-Object -Unique).Count -gt 1) {
|        $out.Reason = 'the tokens handed over are not all for the same identity'; $out.Tokens = @{}; return $out
|    }
|    if (-not $out.Tokens.ContainsKey('https://management.azure.com/')) { $out.Reason = 'the hand-over holds no Azure Resource Manager token'; $out.Tokens = @{}; return $out }
|    $out.TenantId = [string]$tids[0]; $out.IsApp = [bool]$kinds[0]
|    $out.ObjectId = [string](@($oids | Where-Object { $_ }) | Select-Object -First 1)
|    if ($out.IsApp) { $out.Account = $out.AppId }
|    $out.Ok = $true
|    return $out
|}
|
|function Get-SISetupHandoff {
|    <#
|        The hand-over of this process ($global:SI_SetupHandoff), read from $env:SI_HANDOFF_TOKENS the first time it is asked
|        for (then removed from the environment). $null when nothing was handed over. -TenantId: the install's tenant (a
|        hand-over for another tenant THROWS -- never used, never silently replaced by another sign-in).
|    #>
|    param([string]$TenantId)
|    $h = Get-Variable -Scope Global -Name SI_SetupHandoff -ValueOnly -ErrorAction Ignore
|    if (-not ($h -is [hashtable])) {
|        $json = [string][Environment]::GetEnvironmentVariable('SI_HANDOFF_TOKENS')
|        if (-not $json.Trim()) { return $null }
|        $h = Import-SIHandoffTokens -Json $json -TenantId $TenantId
|        [Environment]::SetEnvironmentVariable('SI_HANDOFF_TOKENS', $null)
|        Remove-Item -Path 'env:SI_HANDOFF_TOKENS' -ErrorAction SilentlyContinue
|        $global:SI_SetupHandoff = $h
|    }
|    if (-not $h.Present) { return $null }
|    if (-not $h.Ok) { throw ('The sign-in handed over by the installation page cannot be used: {0}. Nothing was changed. Restart the install with a fresh code from the installation page.' -f $h.Reason) }
|    if ("$TenantId".Trim() -and $h.TenantId -and $h.TenantId -ne "$TenantId".Trim().ToLowerInvariant()) {
|        throw ('The sign-in handed over by the installation page is for tenant {0}, not this installation''s tenant {1}. Nothing was changed. Restart the install from the installation page of tenant {1}.' -f $h.TenantId, "$TenantId".Trim())
|    }
|    return $h
|}
|
|function Test-SISetupHandoffPresent {
|    <# Was a sign-in handed over to this process (and not refused)? Never throws. #>
|    try { return [bool](Get-SISetupHandoff) } catch { return $false }
|}
|
|function Get-SISetupHandoffStatus {
|    <#
|        PURE given -NowUtc. Which handed-over tokens are usable for at least -MinMinutes more: @{ Expired = @(<resource>);
|        Missing = @(<resource>) } over -Resources. Used before each install step, so a step never starts on a token that
|        runs out under it.
|    #>
|    param([Parameter(Mandatory)][hashtable]$Handoff, [string[]]$Resources = @('https://management.azure.com/'), [datetime]$NowUtc = [datetime]::UtcNow, [int]$MinMinutes = $script:SIHandoffMinMinutes)
|    $exp = @(); $miss = @()
|    foreach ($r in $Resources) {
|        $k = Get-SIHandoffResourceKey $r
|        if (-not $Handoff.Tokens.ContainsKey($k)) { $miss += $k; continue }
|        if ($Handoff.Tokens[$k].ExpiresAt -le $NowUtc.AddMinutes($MinMinutes)) { $exp += $k }
|    }
|    @{ Expired = $exp; Missing = $miss }
|}
|
|# ---------------------------------------------------------------------------------------------------------------
|# The loopback listener and the browser
|# ---------------------------------------------------------------------------------------------------------------
|function Get-SIFreeLoopbackPort {
|    <# A free TCP port on the loopback interface (the OS picks it). #>
|    $l = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
|    try { $l.Start(); return ([System.Net.IPEndPoint]$l.LocalEndpoint).Port } finally { $l.Stop() }
|}
|
|function Get-SISignInEdgePath {
|    <# The Microsoft Edge executable on Windows ($null when absent): the sign-in opens InPrivate in it. #>
|    foreach ($b in @(${env:ProgramFiles(x86)}, $env:ProgramFiles)) {
|        if (-not "$b".Trim()) { continue }
|        $p = [IO.Path]::Combine($b, 'Microsoft', 'Edge', 'Application', 'msedge.exe')
|        if (Test-Path -LiteralPath $p) { return $p }
|    }
|    $null
|}
|
|function Open-SISignInBrowser {
|    <#
|        Opens the sign-in page. Never throws: the URL is always printed as well.
|        #564 (PIM's install at customer I, 2026-10-10): a normal browser window opens the DEFAULT profile, whose saved account signs in
|        silently -- the person never sees a credential prompt and lands in the wrong tenant. On Windows the page opens in an
|        Edge InPrivate window (no saved account, the sign-in form always appears); without Edge, the default browser.
|        SI_SIGNIN_BROWSER=none: nothing is opened -- the person pastes the printed address into the right browser profile.
|    #>
|    param([Parameter(Mandatory)][string]$Url)
|    if ("$env:SI_SIGNIN_BROWSER".Trim().ToLowerInvariant() -eq 'none') { return $false }
|    try {
|        if ($PSVersionTable.PSEdition -ne 'Core' -or $IsWindows) {
|            $edge = Get-SISignInEdgePath
|            if ($edge) { Start-Process -FilePath $edge -ArgumentList @('--inprivate', '--new-window', $Url) | Out-Null; return $true }
|            Start-Process -FilePath $Url | Out-Null; return $true
|        }
|        if ($IsMacOS) { & open $Url 2>$null | Out-Null; return $true }
|        & xdg-open $Url 2>$null | Out-Null
|        return $true
|    } catch { return $false }
|}
|
|function Wait-SILoopbackAuthCode {
|    <#
|        Listens on http://localhost:<Port>/ (the loopback interface only) for the browser's redirect, answers it with a
|        short page, and returns the request's query string. -Listener is a test seam (an HttpListener the test drives).
|    #>
|    param([Parameter(Mandatory)][int]$Port, [int]$TimeoutSec = 300, $Listener)
|    $own = $false
|    if (-not $Listener) {
|        $Listener = New-Object System.Net.HttpListener
|        $Listener.Prefixes.Add(('http://localhost:{0}/' -f $Port))
|        $Listener.Start()
|        $own = $true
|    }
|    try {
|        $deadline = [datetime]::UtcNow.AddSeconds($TimeoutSec)
|        while ($true) {
|            $task = $Listener.GetContextAsync()
|            $left = [int][Math]::Max(1, ($deadline - [datetime]::UtcNow).TotalMilliseconds)
|            if (-not $task.Wait($left)) {
|                throw ('No answer from the browser sign-in within {0} seconds. Run the same command again and complete the sign-in in the browser window that opens.' -f $TimeoutSec)
|            }
|            $ctx = $task.Result
|            $query = [string]$ctx.Request.Url.Query
|            $isAnswer = ($query -match '(^|[?&])(code|error)=')
|            $html = if ($isAnswer) {
|                '<!doctype html><html><head><meta charset="utf-8"><title>SecurityInsight sign-in</title></head><body style="font-family:Segoe UI,Arial,sans-serif;margin:40px"><h2>SecurityInsight</h2><p>The sign-in is complete. You can close this window and return to PowerShell.</p></body></html>'
|            } else { '<!doctype html><html><body></body></html>' }
|            $bytes = [System.Text.Encoding]::UTF8.GetBytes($html)
|            try {
|                $ctx.Response.StatusCode = 200
|                $ctx.Response.ContentType = 'text/html; charset=utf-8'
|                $ctx.Response.ContentLength64 = $bytes.Length
|                $ctx.Response.OutputStream.Write($bytes, 0, $bytes.Length)
|            } finally { $ctx.Response.OutputStream.Close(); $ctx.Response.Close() }
|            if ($isAnswer) { return $query }
|            # a favicon or a probe: keep listening for the real redirect
|        }
|    } finally {
|        if ($own) { try { $Listener.Stop(); $Listener.Close() } catch { } }
|    }
|}
|
|# ---------------------------------------------------------------------------------------------------------------
|# Token endpoints
|# ---------------------------------------------------------------------------------------------------------------
|function Invoke-SISignInTokenRequest {
|    <# POST to the Entra v2 token endpoint of -TenantId with -Form. Returns the parsed response; throws Entra's own
|       error text (AADSTS...) in a customer sentence. #>
|    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][System.Collections.IDictionary]$Form, [string]$What = 'Sign-in')
|    $pairs = foreach ($k in $Form.Keys) { '{0}={1}' -f $k, [uri]::EscapeDataString([string]$Form[$k]) }
|    $uri = 'https://login.microsoftonline.com/{0}/oauth2/v2.0/token' -f [uri]::EscapeDataString($TenantId)
|    $r = Invoke-SIAzRestHttp -Method POST -Uri $uri -Body ($pairs -join '&') -ContentType 'application/x-www-form-urlencoded' -TimeoutSec 60
|    $code = [int]$r.StatusCode
|    $j = $null; try { $j = ([string]$r.Content) | ConvertFrom-Json } catch { }
|    if ($code -lt 200 -or $code -ge 300 -or -not $j -or -not $j.access_token) {
|        $msg = if ($j -and $j.error_description) { ([string]$j.error_description -split "`r?`n")[0] } elseif ($code -eq 0) { [string]$r.Content } else { [string]$r.Content }
|        throw ('{0} failed (HTTP {1}): {2}' -f $What, $code, $msg)
|    }
|    return $j
|}
|
|function Get-SICloudShellToken {
|    <# A token for -Resource from the Azure Cloud Shell token endpoint: the person who opened Cloud Shell. #>
|    param([Parameter(Mandatory)][string]$Resource)
|    $ep = Get-SICloudShellEndpoint
|    if (-not $ep) { throw 'This is not Azure Cloud Shell: no Cloud Shell token endpoint (MSI_ENDPOINT) is set.' }
|    $res = ($Resource -replace '/\.default$', '').TrimEnd('/') + '/'
|    $r = Invoke-SIAzRestHttp -Method POST -Uri $ep -Headers @{ Metadata = 'true' } -Body ('resource=' + [uri]::EscapeDataString($res)) `
|             -ContentType 'application/x-www-form-urlencoded' -TimeoutSec 60
|    $j = $null; try { $j = ([string]$r.Content) | ConvertFrom-Json } catch { }
|    if ([int]$r.StatusCode -lt 200 -or [int]$r.StatusCode -ge 300 -or -not $j -or -not $j.access_token) {
|        throw ('Azure Cloud Shell did not hand out a token for {0} (HTTP {1}): {2}. Close and reopen Cloud Shell, then run the same command again.' -f $res, $r.StatusCode, $r.Content)
|    }
|    return [pscustomobject]@{ Token = [string]$j.access_token; ExpiresAt = (Get-SITokenExpiry -Response $j) }
|}
|
|# ---------------------------------------------------------------------------------------------------------------
|# The user session
|# ---------------------------------------------------------------------------------------------------------------
|function Send-SISignInNotice {
|    <#
|        #564: says "waiting: sign-in required for <resource> in tenant <t>" BEFORE a browser window opens -- on the console
|        and to the host's progress feed: $global:SI_SignInNotify = { param($Resource, $TenantId) ... } (the guided install
|        registers it and posts the line as an event, so the status page shows WHY the install waits). Never throws.
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [string]$TenantId)
|    $t = if ("$TenantId".Trim()) { "$TenantId".Trim() } else { 'your organisation' }
|    Write-Host ('waiting: sign-in required for {0} in tenant {1}' -f $Resource, $t) -ForegroundColor Yellow
|    $n = Get-Variable -Scope Global -Name SI_SignInNotify -ValueOnly -ErrorAction Ignore
|    if ($n -is [scriptblock]) { try { & $n $Resource $TenantId } catch { } }
|}
|
|function Assert-SISignInTenant {
|    <# PURE apart from throwing. #564: a token whose tid is not the target tenant (a wrong browser profile or account) is
|       refused before any call is made with it. No target tenant (or not a tenant id) = nothing to compare. #>
|    param([AllowEmptyString()][string]$Token, [string]$TenantId, [string]$Where = 'the browser')
|    if (-not "$TenantId".Trim() -or "$TenantId" -notmatch '^[0-9a-fA-F-]{36}$') { return }
|    $c = ConvertFrom-SISignInJwt $Token
|    $tid = if ($c -and $c.PSObject.Properties['tid']) { [string]$c.tid } else { '' }
|    if ($tid -and $tid -ne $TenantId) {
|        throw ('You signed in to tenant {0} in {1}, but this installation is for tenant {2}. Sign in with an account of tenant {2} (open the address in the browser profile of an admin of that tenant), then run the same command again.' -f $tid, $Where, $TenantId)
|    }
|}
|
|function Test-SISignInInteractive {
|    <# Can this session open a browser for a person? (A seam: tests fake it -- a gate run over SSH is never interactive.) #>
|    $interactive = $true
|    try { $interactive = [Environment]::UserInteractive } catch { }
|    [bool]$interactive
|}
|
|function Invoke-SIBrowserCodeSignIn {
|    <#
|        ONE browser sign-in (authorization code + PKCE on a loopback listener) for -Resource with the public client
|        -ClientId. Returns Entra's token response (access_token, refresh_token, expires_in). The account must belong to
|        -TenantId (#564). -Prompt '' with a -LoginHint lets the browser reuse the person's sign-in (no account picker).
|    #>
|    param(
|        [string]$TenantId,
|        [Parameter(Mandatory)][string]$ClientId,
|        [Parameter(Mandatory)][string]$Resource,
|        [string]$LoginHint,
|        [string]$Prompt = 'select_account',
|        [string]$What = 'Azure Resource Manager',
|        [string]$Title = 'Sign in to Azure in your browser.',
|        [string]$FailText = 'The Azure sign-in',
|        [int]$TimeoutSec = 300
|    )
|    $pkce = New-SIPkcePair
|    $state = New-SIRandomBase64Url -ByteCount 16
|    $port = Get-SIFreeLoopbackPort
|    $redirect = 'http://localhost:{0}/' -f $port
|    $scope = (Get-SISignInScope -Resource $Resource) + ' offline_access openid profile'
|    $url = Get-SIAuthorizeUrl -TenantId $TenantId -ClientId $ClientId -RedirectUri $redirect -Scope $scope -CodeChallenge $pkce.Challenge -State $state -LoginHint $LoginHint -Prompt $Prompt
|    # #564: the reason for the wait is said BEFORE any window opens; the address is always printed
|    Send-SISignInNotice -Resource $What -TenantId $TenantId
|    $who = if ($TenantId) { 'an admin of tenant ' + $TenantId } else { 'the admin who installs' }
|    Write-Host ''
|    Write-Host ('{0} If no window opens, or it opens in the wrong profile or account, open this address in the browser profile of {1}:' -f $Title, $who) -ForegroundColor Cyan
|    Write-Host ('  {0}' -f $url)
|    $null = Open-SISignInBrowser -Url $url
|    $query = Wait-SILoopbackAuthCode -Port $port -TimeoutSec $TimeoutSec
|    $code = Resolve-SIAuthRedirect -Query $query -ExpectedState $state
|    $authTenant = if ($TenantId) { $TenantId } else { 'organizations' }
|    $j = Invoke-SISignInTokenRequest -TenantId $authTenant -What $FailText -Form ([ordered]@{
|        client_id     = $ClientId
|        grant_type    = 'authorization_code'
|        code          = $code
|        redirect_uri  = $redirect
|        code_verifier = $pkce.Verifier
|        scope         = $scope
|    })
|    # #564: the account must belong to the TARGET tenant -- refused here, before any call uses the token
|    Assert-SISignInTenant -Token ([string]$j.access_token) -TenantId $TenantId -Where 'the browser'
|    return $j
|}
|
|function Connect-SISetupUser {
|    <#
|        Signs a PERSON in for setup and records the session in this process (memory only).
|          -Method Auto       Cloud Shell when this is Cloud Shell, else the browser (code + PKCE on a loopback listener)
|          -Method CloudShell the Cloud Shell token endpoint
|          -Method Browser    the browser
|        -TenantId: the tenant to sign in to (the browser signs in there; Cloud Shell must already be in it).
|        Returns the session: Method, TenantId, Account, ObjectId.
|    #>
|    param(
|        [string]$TenantId,
|        [ValidateSet('Auto', 'CloudShell', 'Browser', 'Handoff')][string]$Method = 'Auto',
|        [string]$LoginHint,
|        [int]$TimeoutSec = 300,
|        [string]$ClientId
|    )
|    # #876: a sign-in handed over by the installation page answers first -- nothing is signed in here
|    $ho = $null
|    if ($Method -in 'Auto', 'Handoff') { $ho = Get-SISetupHandoff -TenantId $TenantId }
|    if ($Method -eq 'Handoff' -and -not $ho) { throw 'No sign-in was handed over to this PowerShell session (SI_HANDOFF_TOKENS is not set).' }
|    if ($ho) { $Method = 'Handoff' }
|    if ($Method -eq 'Auto') { $Method = if (Test-SICloudShell) { 'CloudShell' } else { 'Browser' } }
|    $st = Get-SISignInState
|    $st.Tokens = @{}
|    $st['Exchange'] = $null
|    $arm = 'https://management.azure.com/'
|    if ($Method -eq 'Handoff') {
|        $armTok = $ho.Tokens[$arm]
|        if ($armTok.ExpiresAt -le [datetime]::UtcNow.AddMinutes($script:SIHandoffMinMinutes)) { throw (Get-SIHandoffExpiredText -Resource $arm) }
|        $st.Session = @{ Method = 'Handoff'; TenantId = $ho.TenantId; Account = $ho.Account; ObjectId = $ho.ObjectId; IsApp = [bool]$ho.IsApp; AppId = $ho.AppId; RefreshToken = $null; ClientId = $null }
|        foreach ($k in @($ho.Tokens.Keys)) { $st.Tokens[$k] = @{ Token = $ho.Tokens[$k].Token; ExpiresAt = $ho.Tokens[$k].ExpiresAt } }
|        Write-Host ('Using the sign-in handed over by the installation page: {0} {1} (tenant {2}) -- no sign-in here.' -f $(if ($ho.IsApp) { 'the application' } else { 'the account' }), $ho.Account, $ho.TenantId) -ForegroundColor Green
|        return [pscustomobject]@{ Method = 'Handoff'; TenantId = $ho.TenantId; Account = $ho.Account; ObjectId = $ho.ObjectId; IsApp = [bool]$ho.IsApp }
|    }
|    if ($Method -eq 'CloudShell') {
|        $t = Get-SICloudShellToken -Resource $arm
|        $c = ConvertFrom-SISignInJwt $t.Token
|        $tid = if ($c) { [string]$c.tid } else { '' }
|        if ($TenantId -and $tid -and $tid -ne $TenantId) {
|            throw ("Azure Cloud Shell is signed in to tenant {0}, but this needs tenant {1}. Switch directory in the Azure portal (Settings > Directories), reopen Cloud Shell, then run the same command again." -f $tid, $TenantId)
|        }
|        $st.Session = @{ Method = 'CloudShell'; TenantId = $tid; Account = (Get-SISignInAccountName $c); ObjectId = $(if ($c) { [string]$c.oid } else { '' }); RefreshToken = $null; ClientId = $null }
|        $st.Tokens[$arm] = @{ Token = $t.Token; ExpiresAt = $t.ExpiresAt }
|    } else {
|        if (Test-SICloudShell) {
|            # #564: Cloud Shell has its own token endpoint (-Method CloudShell / Auto); a localhost answer cannot reach it
|            throw 'Azure Cloud Shell cannot take the browser sign-in''s answer (it goes to localhost on your own machine). In Cloud Shell setup signs in through Cloud Shell itself: run the same command without asking for the browser sign-in.'
|        }
|        if (-not (Test-SISignInInteractive)) {
|            throw 'A person has to sign in for this step, and this PowerShell session cannot open a browser. Run it in an interactive session or in Azure Cloud Shell, or sign in with an app (certificate or client secret).'
|        }
|        if (-not $ClientId) { $ClientId = Get-SISignInClientId }
|        $j = Invoke-SIBrowserCodeSignIn -TenantId $TenantId -ClientId $ClientId -Resource $arm -LoginHint $LoginHint -TimeoutSec $TimeoutSec
|        $c = ConvertFrom-SISignInJwt ([string]$j.access_token)
|        $tid = if ($c -and $c.tid) { [string]$c.tid } else { $TenantId }
|        $st.Session = @{ Method = 'Browser'; TenantId = $tid; Account = (Get-SISignInAccountName $c); ObjectId = $(if ($c) { [string]$c.oid } else { '' }); RefreshToken = [string]$j.refresh_token; ClientId = $ClientId }
|        $st.Tokens[$arm] = @{ Token = [string]$j.access_token; ExpiresAt = (Get-SITokenExpiry -Response $j) }
|    }
|    Write-Host ('Signed in to Azure as {0} (tenant {1}, {2}).' -f $st.Session.Account, $st.Session.TenantId, $(if ($st.Session.Method -eq 'CloudShell') { 'Azure Cloud Shell' } else { 'browser sign-in' })) -ForegroundColor Green
|    return [pscustomobject]@{ Method = $st.Session.Method; TenantId = $st.Session.TenantId; Account = $st.Session.Account; ObjectId = $st.Session.ObjectId }
|}
|
|function Test-SISetupUserSignedIn {
|    $st = Get-SISignInState
|    return ($st.Session -is [hashtable])
|}
|
|function Get-SISetupUserToken {
|    <# A token for -Resource as the signed-in person: memory cache, else the Cloud Shell endpoint or the refresh token. #>
|    param([Parameter(Mandatory)][string]$Resource, [switch]$ForceRefresh)
|    $st = Get-SISignInState
|    $s = $st.Session
|    if (-not ($s -is [hashtable])) { throw 'No one is signed in to Azure in this PowerShell session. Run the same command again to sign in.' }
|    $res = ($Resource -replace '/\.default$', '').TrimEnd('/') + '/'
|    if ($s.Method -eq 'Handoff') {
|        # #876: a handed-over token cannot be renewed here (no refresh token crosses over): one that is about to run out
|        # stops the step with one plain line, and the install resumes from that step with a fresh hand-over
|        $k = Get-SIHandoffResourceKey $res
|        $hit = $null
|        foreach ($tk in @($st.Tokens.Keys)) { if ((Get-SIHandoffResourceKey $tk) -eq $k) { $hit = $st.Tokens[$tk]; break } }
|        if (-not $hit) {
|            throw ('The sign-in handed over by the installation page holds no token for {0}, which this step needs. Nothing more was changed. Restart the install with a hand-over that includes {0} (the install resumes where it stopped).' -f $k.TrimEnd('/'))
|        }
|        if ($hit.ExpiresAt -le [datetime]::UtcNow.AddMinutes($script:SIHandoffMinMinutes)) { $global:SI_SetupHandoffExpired = $k; throw (Get-SIHandoffExpiredText -Resource $k) }
|        return [string]$hit.Token
|    }
|    if (-not $ForceRefresh -and $st.Tokens.ContainsKey($res) -and $st.Tokens[$res].ExpiresAt -gt [datetime]::UtcNow) { return [string]$st.Tokens[$res].Token }
|    if ($s.Method -eq 'CloudShell') {
|        $t = Get-SICloudShellToken -Resource $res
|        $st.Tokens[$res] = @{ Token = $t.Token; ExpiresAt = $t.ExpiresAt }
|        return $t.Token
|    }
|    if (Test-SISignInExchangeResource -Resource $res) {
|        # Exchange Online takes only a token of its own client (Exchange.Manage): its own refresh token, and the first time
|        # one more browser sign-in -- the same account pre-filled, so the browser normally signs straight in.
|        $xc = Get-SISignInExchangeClientId
|        $x = $st['Exchange']
|        $j = $null
|        if ($x -is [hashtable] -and $x.RefreshToken -and $x.ClientId -eq $xc) {
|            try {
|                $j = Invoke-SISignInTokenRequest -TenantId $s.TenantId -What 'Getting a token for Exchange Online' -Form ([ordered]@{
|                    client_id = $xc; grant_type = 'refresh_token'; refresh_token = $x.RefreshToken; scope = (Get-SISignInScope -Resource $res) + ' offline_access' })
|            } catch { $j = $null }
|        }
|        if (-not $j) {
|            if (-not (Test-SISignInInteractive)) { throw 'Exchange Online needs its own sign-in in the browser, and this PowerShell session cannot open a browser. Run it in an interactive PowerShell window.' }
|            $j = Invoke-SIBrowserCodeSignIn -TenantId $s.TenantId -ClientId $xc -Resource $res -LoginHint ([string]$s.Account) -Prompt '' `
|                     -What 'Exchange Online' -Title 'Sign in once more, for Exchange Online (it accepts only its own sign-in; your account is filled in).' -FailText 'The Exchange Online sign-in'
|        }
|        $st['Exchange'] = @{ ClientId = $xc; RefreshToken = $(if ($j.refresh_token) { [string]$j.refresh_token } elseif ($x -is [hashtable]) { $x.RefreshToken } else { $null }) }
|        Assert-SISignInTenant -Token ([string]$j.access_token) -TenantId ([string]$s.TenantId) -Where 'the token for Exchange Online'
|        $st.Tokens[$res] = @{ Token = [string]$j.access_token; ExpiresAt = (Get-SITokenExpiry -Response $j) }
|        return [string]$j.access_token
|    }
|    if (-not $s.RefreshToken) { throw 'The Azure sign-in has expired. Run the same command again to sign in.' }
|    $j = Invoke-SISignInTokenRequest -TenantId $s.TenantId -What ('Getting a token for {0}' -f $res) -Form ([ordered]@{
|        client_id     = $s.ClientId
|        grant_type    = 'refresh_token'
|        refresh_token = $s.RefreshToken
|        scope         = (Get-SISignInScope -Resource $res) + ' offline_access'
|    })
|    if ($j.refresh_token) { $s.RefreshToken = [string]$j.refresh_token }   # Entra rotates it
|    Assert-SISignInTenant -Token ([string]$j.access_token) -TenantId ([string]$s.TenantId) -Where ('the token for ' + $res)
|    $st.Tokens[$res] = @{ Token = [string]$j.access_token; ExpiresAt = (Get-SITokenExpiry -Response $j) }
|    return [string]$j.access_token
|}
|
|function Disconnect-SISetupUser {
|    $st = Get-SISignInState
|    $st.Session = $null
|    $st.Tokens = @{}
|    $st['Exchange'] = $null
|}
'@ }
$__siSupportFiles['setup/_shared/SI-SqlAdminReady.ps1'] = @{ Sha256 = '2461ccb8704ea8e6e5046ab6b443f9421df1ef6abd6200cbbc3c71147602bc6a'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight SETUP -- a database server's NEW Entra administrator is waited for before anyone signs in with it (#695).
|
|    Why: the customer-run install at customer B, 2026-10-15 (read from Azure's activity log). 07:50:06Z the installer set
|    the SQL server's Entra admin (Microsoft.Sql/servers/administrators/write, the admin group, Entra-only sign-in) and Azure
|    answered Accepted -- the change is ASYNCHRONOUS; 07:50:14-19Z the installer signed in to the database and was refused
|    ("Login failed for user '<token-identified principal>'"); 07:50:22Z Azure finished the admin write (Succeeded). The
|    read-back of the administrators resource shows the new admin AT ONCE, while the server is still taking it, so a read
|    back alone does not prove the change is done.
|
|      Wait-SIArmAsyncOperation   after an ARM write answered 201/202: polls Azure's own operation (Azure-AsyncOperation,
|                                 else Location) until it is finished. Bounded; a failed operation throws with Azure's words.
|      Wait-SISqlAdminWrite       after the admin write: the operation finished AND the admin read back is the expected one.
|      Test-SISqlAdminIs          PURE: is this administrators resource the expected principal (sid, and login when given)?
|      Test-SISqlLoginNotReady    PURE: is this error text the refusal of an Entra token sign-in -- the answer of a server
|                                 that does not know its new administrator yet? A wrong password, a firewall refusal or any
|                                 other SQL error is NOT.
|      Invoke-SISqlLoginRetry     the first sign-in after the administrator was set: ONLY that refusal, and only within the
|                                 first minutes after the admin was set, is waited out (30 s at a time, up to 5 minutes),
|                                 with one plain line; then the real message. Every other error returns / throws at once.
|
|    No PowerShell module: the REST calls are a scriptblock the caller passes (Invoke-SIAzRestMethod in setup). PS 5.1 safe.
|#>
|
|function Get-SIArmAsyncOperationUrl {
|    <# PURE. The URL Azure gave to follow an accepted write: @{ Url; Kind = 'AsyncOperation' | 'Location' }, $null when
|       the answer names none (a write that finished at once). -Response: StatusCode + Headers (any dictionary). #>
|    param($Response)
|    if ($null -eq $Response) { return $null }
|    $h = $null; $pp = $Response.PSObject.Properties['Headers']; if ($pp) { $h = $pp.Value } elseif ($Response -is [System.Collections.IDictionary]) { $h = $Response['Headers'] }
|    if (-not ($h -is [System.Collections.IDictionary])) { return $null }
|    $find = { param([string]$name) foreach ($k in @($h.Keys)) { if ([string]$k -ieq $name) { $v = $h[$k]; if ($v -is [array]) { $v = $v[0] }; if ("$v".Trim()) { return "$v".Trim() } } }; $null }
|    $a = & $find 'Azure-AsyncOperation'
|    if ($a) { return [pscustomobject]@{ Url = $a; Kind = 'AsyncOperation' } }
|    $l = & $find 'Location'
|    if ($l) { return [pscustomobject]@{ Url = $l; Kind = 'Location' } }
|    $null
|}
|
|function Wait-SIArmAsyncOperation {
|    <#
|        After an ARM write: when Azure answered 201/202 with an operation to follow, polls it until it is FINISHED --
|        Azure-AsyncOperation: its status Succeeded (Failed / Canceled THROW with Azure's error); Location: 202 = still
|        running, 200/204 = done. A write that finished at once (no operation named) returns at once. Bounded (-TimeoutSec,
|        polls every -PollSec); at the deadline it THROWS. One plain line while it waits (-Print). Returns $true when it
|        waited on an operation, $false when there was none.
|        -Rest { param([string]$Method, [string]$Path) } -> @{ StatusCode; Content } (Invoke-SIAzRestMethod in setup).
|    #>
|    param($Response, [Parameter(Mandatory)][scriptblock]$Rest, [int]$TimeoutSec = 600, [int]$PollSec = 10,
|          [scriptblock]$Sleep, [scriptblock]$Print, [string]$What = 'the change')
|    $code = 0; try { $code = [int]$Response.StatusCode } catch { $code = 0 }
|    if ($code -notin 201, 202) { return $false }
|    $op = Get-SIArmAsyncOperationUrl -Response $Response
|    if (-not $op) { return $false }
|    $polls = [Math]::Max(1, [int][Math]::Ceiling($TimeoutSec / [double][Math]::Max(1, $PollSec)))
|    $said = $false; $state = 'accepted'
|    for ($i = 0; $i -le $polls; $i++) {
|        $r = $null; try { $r = & $Rest 'GET' $op.Url } catch { $r = $null }
|        $sc = 0; try { $sc = [int]$r.StatusCode } catch { $sc = 0 }
|        $j = $null; try { if ($r -and "$($r.Content)".Trim()) { $j = [string]$r.Content | ConvertFrom-Json } } catch { $j = $null }
|        if ($op.Kind -eq 'AsyncOperation') {
|            $st = ''; if ($j -and $j.PSObject.Properties['status']) { $st = [string]$j.status }
|            if ($st -ieq 'Succeeded') { return $true }
|            if ($st -in 'Failed', 'Canceled', 'Cancelled') {
|                $why = ''; if ($j.PSObject.Properties['error'] -and $j.error) { $why = $(if ($j.error.PSObject.Properties['message']) { [string]$j.error.message } else { [string]($j.error | ConvertTo-Json -Compress -Depth 5) }) }
|                throw ('{0}: Azure reports it {1}{2}' -f $What, $st, $(if ($why) { ' -- ' + $why } else { '' }))
|            }
|            if ($st) { $state = $st }
|        } else {
|            if ($sc -in 200, 204) { return $true }
|            if ($sc -ge 400) { throw ('{0}: Azure reports it failed ({1}){2}' -f $What, $sc, $(if ($r -and "$($r.Content)".Trim()) { ' -- ' + [string]$r.Content } else { '' })) }
|            if ($sc -eq 202) { $state = 'in progress' }
|        }
|        if ($i -ge $polls) { break }
|        if (-not $said -and $Print) { & $Print ('       Azure is still applying {0} -- waiting until it is done ...' -f $What); $said = $true }
|        if ($Sleep) { & $Sleep $PollSec } else { Start-Sleep -Seconds $PollSec }
|    }
|    throw ('{0} is not finished {1} seconds after Azure accepted it (Azure shows: {2}).' -f $What, $TimeoutSec, $state)
|}
|
|function Test-SISqlAdminIs {
|    <# PURE. Is -Admin (the administrators resource as read, or its properties) the principal -Sid, named -Login when given? #>
|    param($Admin, [Parameter(Mandatory)][string]$Sid, [string]$Login)
|    if ($null -eq $Admin) { return $false }
|    $p = $Admin; $pp = $Admin.PSObject.Properties['properties']; if ($pp -and $pp.Value) { $p = $pp.Value }
|    $s = ''; $sp = $p.PSObject.Properties['sid']; if ($sp) { $s = [string]$sp.Value }
|    if ($s -ine $Sid) { return $false }
|    if ($Login) { $l = ''; $lp = $p.PSObject.Properties['login']; if ($lp) { $l = [string]$lp.Value }; if ($l -ne $Login) { return $false } }
|    $true
|}
|
|function Wait-SISqlAdminWrite {
|    <#
|        After the write of a database server's Entra administrator (PUT .../administrators/ActiveDirectory): WAITS until
|        Azure has FINISHED it (Wait-SIArmAsyncOperation on the answer of the write) and READS BACK that the administrator is
|        -Sid (named -Login when given). Both inside ONE bounded window (-TimeoutSec, -PollSec steps). THROWS when the write
|        failed, or when the administrator read back is still not the expected one at the deadline. Returns the
|        administrators resource as read.
|        -Rest { param([string]$Method, [string]$Path) } -> @{ StatusCode; Content }; -AdminPath: the administrators resource
|        (with its api-version).
|    #>
|    param($Response, [Parameter(Mandatory)][scriptblock]$Rest, [Parameter(Mandatory)][string]$AdminPath, [Parameter(Mandatory)][string]$Sid,
|          [string]$Login, [int]$TimeoutSec = 600, [int]$PollSec = 10, [scriptblock]$Sleep, [scriptblock]$Print, [string]$What = 'the new Entra admin')
|    $started = [datetime]::UtcNow
|    $null = Wait-SIArmAsyncOperation -Response $Response -Rest $Rest -TimeoutSec $TimeoutSec -PollSec $PollSec -Sleep $Sleep -Print $Print -What $What
|    # the rest of the window for the read-back (a test's instant -Sleep: at most TimeoutSec / PollSec reads)
|    $left = [Math]::Max($PollSec, $TimeoutSec - [int]([datetime]::UtcNow - $started).TotalSeconds)
|    $polls = [Math]::Max(1, [int][Math]::Ceiling($left / [double][Math]::Max(1, $PollSec)))
|    $after = $null; $said = $false
|    for ($i = 0; $i -le $polls; $i++) {
|        $after = $null
|        try { $r = & $Rest 'GET' $AdminPath; if ($r -and [int]$r.StatusCode -lt 300 -and "$($r.Content)".Trim()) { $after = [string]$r.Content | ConvertFrom-Json } } catch { $after = $null }
|        if (Test-SISqlAdminIs -Admin $after -Sid $Sid -Login $Login) { return $after }
|        if ($i -ge $polls) { break }
|        if (-not $said -and $Print) { & $Print ('       {0} is not shown on the server yet -- waiting until it is ...' -f $What); $said = $true }
|        if ($Sleep) { & $Sleep $PollSec } else { Start-Sleep -Seconds $PollSec }
|    }
|    $shown = 'none, or the server could not be read'
|    if ($after) { $p = $after; if ($after.PSObject.Properties['properties'] -and $after.properties) { $p = $after.properties }; $shown = [string]$p.login }
|    throw ('{0} did not take effect within {1} seconds (the server shows: {2}) -- check the server' -f $What, $TimeoutSec, $shown)
|}
|
|function Test-SISqlLoginNotReady {
|    <# PURE. The refusal of an ENTRA TOKEN sign-in ("Login failed for user '<token-identified principal>'") -- what a server
|       answers while it does not know its new Entra administrator yet. A wrong password ("Login failed for user 'sa'"), a
|       firewall refusal, a missing database or any other SQL error is not. #>
|    param([AllowEmptyString()][AllowNull()][string]$Text)
|    [bool]("$Text" -match "(?i)Login failed for user\s+'<token-identified principal>'")
|}
|
|function Invoke-SISqlLoginRetry {
|    <#
|        Runs -Action (the first sign-in after the database server's administrator was set). When it answers the refusal of
|        Test-SISqlLoginNotReady -- thrown, or in the .Error of the result it returns -- AND the administrator was set within
|        the last -WindowSec seconds (-AdminSetAt, UTC), it is waited for (-StepSec at a time, up to -WaitSec in all) with one
|        plain line, then run again. After that the real answer: the result as it came, or the error thrown again. Any
|        other error is never retried. Returns the action's result.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Action, $AdminSetAt, [scriptblock]$Now, [scriptblock]$Sleep, [scriptblock]$Print,
|          [int]$WaitSec = 300, [int]$StepSec = 30, [int]$WindowSec = 900)
|    $nowFn = $(if ($Now) { $Now } else { { [datetime]::UtcNow } })
|    $setAt = $null
|    if ($AdminSetAt -is [datetime]) { $setAt = $AdminSetAt }
|    elseif ("$AdminSetAt".Trim()) { $d = [datetime]::MinValue; if ([datetime]::TryParse("$AdminSetAt", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AdjustToUniversal -bor [Globalization.DateTimeStyles]::AssumeUniversal, [ref]$d)) { $setAt = $d } }
|    $waited = 0; $said = $false
|    while ($true) {
|        $result = $null; $thrown = $null
|        try { $result = & $Action } catch { $thrown = $_ }
|        $text = $(if ($thrown) { [string]$thrown.Exception.Message } elseif ($result -and $result.PSObject.Properties['Error']) { [string]$result.Error } else { '' })
|        $recent = $false
|        if ($setAt) { $recent = ((([datetime](& $nowFn)).ToUniversalTime() - $setAt.ToUniversalTime()).TotalSeconds -le $WindowSec) }
|        if (-not $text -or -not (Test-SISqlLoginNotReady -Text $text) -or -not $recent -or $waited -ge $WaitSec) {
|            if ($thrown) { throw $thrown }
|            return $result
|        }
|        if (-not $said -and $Print) { & $Print ('       the database server does not let the sign-in in yet: its new administrator was set moments ago -- waiting {0} s at a time (up to {1} minutes) ...' -f $StepSec, [Math]::Ceiling($WaitSec / 60.0)); $said = $true }
|        if ($Sleep) { & $Sleep $StepSec } else { Start-Sleep -Seconds $StepSec }
|        $waited += $StepSec
|    }
|}
'@ }
$__siSupportFiles['setup/_shared/SI-GroupMemberAdd.ps1'] = @{ Sha256 = '7c9f6ea589b0b3655150907a349d953ca444906b7b30d583afead8e1a0b1b9ee'; Text = @'
|#Requires -Version 5.1
|<#
|.SYNOPSIS
|    SecurityInsight -- adding a member to an Entra group that was created moments ago: wait out Entra replication, then
|    read the membership back (owner rule: "after a REST create, wait and read back").
|
|.DESCRIPTION
|    #1092 (a private Pro install on 3.0.31): the in-network SQL identity could not be added to the database admin group a
|    few minutes after Set-SISqlAdminGroup made it -- Microsoft Graph answered 404 "Resource 'Group_<id>' does not exist or
|    one of its queried reference-property objects are not present" (the new group had not reached every directory replica
|    yet), and the step ended as a warning that sent the customer to Invardia support.
|
|    Invoke-SIGroupMemberAddRetry is the ONE policy for every place SecurityInsight adds a group member right after the
|    group (or the member) was created -- Set-SISqlAdminGroup.ps1, the private-network step's SQL identity and the Support
|    app's membership (Set-SISupportAppGroupMember), Grant-SISupportAccess.ps1:
|      * the add is tried; ONLY a "not found" answer (404 / Request_ResourceNotFound / does not exist) is waited for and
|        tried again, with a growing wait (5, 10, 20, 40, then 60 seconds), up to -LimitSeconds in all (default 300 =
|        5 minutes, said in the log line);
|      * "already exists" counts as added; any other answer (a refusal: 403, Authorization_RequestDenied) stops at once;
|      * an add that went through is READ BACK (-Test, asked from the member's side) with short waits;
|      * only past the limit is it given up -- State 'notfound', which the caller turns into its warning.
|    The caller hands in the two calls as script blocks, so the POST and the member-side check stay in each caller's own
|    words, and the tests run it offline:
|        -Add  { }  the POST of the member; throws on a refusal
|        -Test { }  $true when the membership reads back; throws when the directory cannot be asked
|    Returns [pscustomobject]@{ State; Detail; Error; WaitedSeconds }:
|        added      added (or already there), and read back
|        unchecked  added, but the directory does not show it yet within the read-back waits
|        refused    the add was refused (Error = the directory's answer)
|        notfound   the directory still did not know the group (or the member) when the limit was reached
|    (A file loaded from inside a function: nothing here depends on a value of its own script scope.)
|#>
|
|function Get-SIGroupMemberAddWaits {
|    <# PURE. The waits between the tries of an add that answered "not found": 5, 10, 20, 40, then 60 seconds each, the last
|       one cut so that together they are exactly -LimitSeconds. #>
|    param([int]$LimitSeconds = 300)
|    $out = New-Object System.Collections.Generic.List[int]
|    $total = 0; $next = 5
|    while ($total -lt $LimitSeconds) {
|        $w = [Math]::Min($next, $LimitSeconds - $total)
|        $out.Add($w); $total += $w
|        $next = [Math]::Min($next * 2, 60)
|    }
|    $out.ToArray()
|}
|
|function Test-SIGroupMemberAddNotYet {
|    <# PURE. Is this answer to a member add "the directory does not know the group / the member YET" (Entra replication)?
|       A refusal is never "not yet", even when its text also says "not found". #>
|    param([AllowNull()][AllowEmptyString()][string]$Message)
|    $t = [string]$Message
|    if ($t -match '(?i)\b403\b|Authorization_RequestDenied|Insufficient privileges|Forbidden') { return $false }
|    [bool]($t -match '(?i)\b404\b|Request_ResourceNotFound|ResourceNotFound|does not exist|not found|NotFound')
|}
|
|function Get-SIGroupMemberAddLimitText {
|    <# PURE. The limit as people read it: "5 minutes", "1 minute", "45 seconds". #>
|    param([int]$LimitSeconds = 300)
|    if ($LimitSeconds -lt 60) { return ('{0} seconds' -f $LimitSeconds) }
|    $m = [int][Math]::Ceiling($LimitSeconds / 60.0)
|    if ($m -eq 1) { '1 minute' } else { '{0} minutes' -f $m }
|}
|
|function Invoke-SIGroupMemberAddRetry {
|    param([Parameter(Mandatory)][scriptblock]$Add, [Parameter(Mandatory)][scriptblock]$Test, [string]$What = 'the member',
|          [scriptblock]$Sleep, [scriptblock]$Print, [int]$LimitSeconds = 300, [int[]]$ReadBackWaits = @(5, 10, 15, 30))
|    # names of their own: the -Add / -Test blocks run in the CALLER's variables ($grp, $sp, $Graph, $GroupId ...)
|    $siGmWaits = @(Get-SIGroupMemberAddWaits -LimitSeconds $LimitSeconds)
|    $siGmLimit = Get-SIGroupMemberAddLimitText -LimitSeconds $LimitSeconds
|    $siGmWaited = 0; $siGmTry = 0; $siGmDone = $false; $siGmErr = ''; $siGmSaid = $false
|    $siGmNap = { param($s) if ($s -le 0) { return }; if ($Sleep) { & $Sleep $s } else { Start-Sleep -Seconds $s } }
|    $siGmSay = { param($t) if ($Print) { & $Print $t } else { Write-Host $t -ForegroundColor DarkGray } }
|    $siGmOut = { param($st, $d) [pscustomobject]@{ State = $st; Detail = [string]$d; Error = $siGmErr; WaitedSeconds = $siGmWaited } }
|    while (-not $siGmDone) {
|        try { $null = & $Add; $siGmDone = $true }
|        catch {
|            $siGmErr = ('{0} {1}' -f [string]$_.Exception.Message, $(if ($_.ErrorDetails) { [string]$_.ErrorDetails.Message } else { '' })).Trim()
|            if ($siGmErr -match '(?i)already exist') { $siGmDone = $true; break }
|            if (-not (Test-SIGroupMemberAddNotYet -Message $siGmErr)) { return (& $siGmOut 'refused' ('{0} could not be added: {1}' -f $What, $siGmErr)) }
|            if ($siGmTry -ge $siGmWaits.Count) {
|                return (& $siGmOut 'notfound' ('{0} could not be added: the directory still answers "not found" after {1} of waiting for the new group to replicate (Entra) -- {2}' -f $What, $siGmLimit, $siGmErr))
|            }
|            if (-not $siGmSaid) {
|                & $siGmSay ('      [waiting ] the directory does not know the new group (or {0}) yet -- Entra replication; trying again for up to {1}' -f $What, $siGmLimit)
|                $siGmSaid = $true
|            }
|            $siGmW = [int]$siGmWaits[$siGmTry]; $siGmTry++
|            & $siGmNap $siGmW; $siGmWaited += $siGmW
|        }
|    }
|    # READ BACK: the membership the directory HAS, not the request it accepted
|    $siGmLast = ''
|    foreach ($siGmR in @(0) + @($ReadBackWaits)) {
|        & $siGmNap ([int]$siGmR)
|        try { if (& $Test) { return (& $siGmOut 'added' ('{0} added, and read back from the directory{1}' -f $What, $(if ($siGmWaited) { (' (after {0} s of Entra replication)' -f $siGmWaited) } else { '' }))) } }
|        catch { $siGmLast = [string]$_.Exception.Message }
|    }
|    & $siGmOut 'unchecked' ('could not be checked: the member was added, but the directory does not show it yet{0}' -f $(if ($siGmLast) { ' (' + $siGmLast + ')' } else { '' }))
|}
'@ }
$__siSupportFiles['setup/_shared/SI-DbInitJob.ps1'] = @{ Sha256 = '15d34c0be0bdcb253a2297142ea95d1fff4a2468fbe00857ce1ad7ad44db754c'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- THE DATABASE SETUP JOB caj-si-dbinit (framework SEC-08 "no person needs database admin rights at an
|    install"; Invardia DESIGN ch 12 binding spec points 1-10, agreed by SI, PIM and EPS 2026-11-03; SI REQUIREMENTS #1072).
|
|    WHAT IT IS
|      * ONE Container Apps job per install, caj-si-dbinit, MANUAL trigger, running the install's own engine image (the
|        si-orchestrator image every engine job runs -- no new image to sign) with its own entry point
|        container/Start-SIDbInit.ps1.
|      * It runs as its OWN user-assigned identity id-si-dbinit, a STANDING member of the install's SQL admin group (the group
|        that is the SQL server's Entra administrator: grp-si-sql-admins, or the install's own group). The server's
|        administrator is never switched for it.
|      * It does the database work that needed a person in that group: every product identity's contained user by its client
|        id (engine, web, MCP, updater, asset tagging) with its roles and grants, the updater's rights, the signed grant
|        procedure, the web app's sign-in front schema, and -- only when the caller names the Invardia Support app -- that
|        app's own database user and the support grant procedures. Every statement is the SQL the person-run script already
|        sends (Get-SIEngineDatabaseAccessSql, Get-SIUpdaterDatabaseAccessSql, Get-SIGrantProcedureAdminSql,
|        Get-SIManagementUserSql, Get-SITaggingDatabaseAccessSql, Get-SISigninStoreSql, Get-SISupportAppDatabaseAccessSql,
|        Get-SISupportGrantAdminSteps) -- never a second copy of it.
|      * Every principal and grant is READ BACK; the job writes ONE result row (cfg.InstallState 'DbJob', Value <= 400
|        characters) and exits non-zero on any failure.
|
|    WHO STARTS IT
|      * the guided install (step db-job): makes the identity, adds it to the admin group and READS THE MEMBERSHIP BACK from
|        the identity's side (memberOf -- a group's /members list hides service principals from many callers, EPS 2.0.59),
|        only THEN makes and starts the job (a managed identity's token is cached for hours: a run before the membership exists
|        keeps a token without the group), waits, and reads the execution's result;
|      * the updater, on every update, BEFORE the database step: keeps the identity and the job present; framework §4.5
|        SQL-ADMIN-GROUP G2-G5: it CONVERGES and RENEWS the identity's membership (Sync-SIDbInitMembership, the same path as
|        setup) with its own G5 Graph permissions (three PIM-for-Groups + GroupMember.Read.All + Application.Read.All), which setup grants (Grant-SIDbInitUpdaterGraphRoles) and
|        the updater only checks (Test-SIDbInitUpdaterGraphRoles); it starts the job once the membership reads back or a run
|        of it proved it (a 'DbJob' row the job itself wrote) -- until then the update keeps today's path and the heartbeat's
|        setup step db-job asks for the one membership; a failed run holds the update (nothing is rolled, the old version
|        keeps running), and so does a proven membership that is gone and cannot be made again;
|      * Invardia support for a repair (setup\Start-SIDbInitJob.ps1).
|
|    Seams (callers hand them in, tests pass fakes):
|      -Sql   { param([string]$Database, [string]$Query, $Params, [string]$Mode) }  Mode nonquery | rows; rows = hashtables
|      -Arm   { param([string]$Method, [string]$Path, $Body) }  parsed answer; $null = not found on a GET; throws otherwise
|      -Graph { param([string]$Method, [string]$Uri, $Body) }   parsed answer; throws on an error
|    The SQL builders above must be loaded by the caller (Import-SIDbInitSqlSources does it from a SecurityInsight root).
|    PS 5.1 safe; no module.
|#>
|
|function Get-SIDbInitNames {
|    <# PURE. The fixed names (a function, not a $script: value: a caller that dot-sources this file inside a function sees it). #>
|    [ordered]@{
|        Job            = 'caj-si-dbinit'
|        Identity       = 'id-si-dbinit'
|        Record         = 'DbJob'
|        Container      = 'dbinit'
|        Entry          = '/app/container/Start-SIDbInit.ps1'
|        TagName        = 'si-component'
|        TagValue       = 'dbinit'
|        ProDatabase    = 'sqldb-si-pro'
|        LedgerDatabase = 'sqldb-si-identity'
|        AppApi         = '2025-07-01'
|        MiApi          = '2023-01-31'
|        RecordMax      = 400
|        # framework §4.5 SQL-ADMIN-GROUP G2-G4: the membership's own row (the updater's last check of it) and the renewal window
|        MembershipRecord = 'DbJobMembership'
|        RenewWindowDays  = 30
|        SqlApi           = '2021-11-01'
|        # #1146: a statement chosen as a DEADLOCK victim (SQL 1205) is sent again after these waits (seconds), said each time
|        DeadlockWaits    = @(2, 5, 10)
|        # #1146: an updater execution counts as running for at most this long when its job names no run limit (seconds)
|        UpdaterLimitSeconds = 21600
|        UpdaterLockStaleMinutes = 15
|    }
|}
|
|function Get-SIDbInitCallerRecordName {
|    <# PURE. #1146: the result row of ONE caller (installer | updater | support | job): 'DbJobUpdater' ... -- written by the
|       job next to the shared row 'DbJob', so a run started beside another (a support setup beside an update) can never
|       overwrite the result the other caller waits for. #>
|    param([AllowEmptyString()][string]$By = '')
|    $b = "$By".Trim().ToLowerInvariant()
|    if ($b -notin 'installer', 'updater', 'support', 'job') { $b = 'job' }
|    (Get-SIDbInitNames).Record + $b.Substring(0, 1).ToUpperInvariant() + $b.Substring(1)
|}
|
|function Test-SIDbInitDeadlock {
|    <# PURE. #1146: is this SQL error a DEADLOCK victim (SQL 1205) -- a statement SQL rolled back so another could finish, which
|       may be sent again? (live 2026-11-07, install-a: "Transaction ... was deadlocked ... and has been chosen as the deadlock victim".) #>
|    param([AllowNull()][AllowEmptyString()][string]$Message)
|    [bool]("$Message" -match '(?i)chosen as the deadlock victim|was deadlocked on|\bdeadlock victim\b|\b1205\b')
|}
|
|function Get-SIDbInitComponents { <# PURE. The product identities the job makes users for, in order. #> @('engine', 'updater', 'web', 'mcp', 'tagging') }
|
|function Import-SIDbInitSqlSources {
|    <# Dot-sources the SQL builders the job reuses, from -SIRoot, into the CALLER's scope (call it dot-sourced:
|       . Import-SIDbInitSqlSources -SIRoot $r). A file a package does not carry is left out; its steps are then not planned. #>
|    param([Parameter(Mandatory)][string]$SIRoot)
|    foreach ($rel in @('engine/pro-settings/SI-EngineGrants.ps1', 'engine/pro-settings/SI-ProSchema.ps1', 'engine/pro-settings/SI-GrantProcedure.ps1',
|                       'engine/pro-settings/SI-SupportGrantSql.ps1', 'pro-management/deploy/SI-ManagementGrants.ps1', 'pro-management/deploy/SI-SigninFrontStore.ps1',
|                       'setup/_shared/SI-SupportAppDatabase.ps1', 'setup/_shared/SI-SupportGrantUpdate.ps1', 'setup/_shared/SI-IdentityMoveSql.ps1')) {
|        $p = [IO.Path]::Combine($SIRoot, $rel)
|        if (Test-Path -LiteralPath $p) { . $p }
|    }
|}
|
|function Get-SIDbInitSid {
|    <# PURE. An Entra principal's database SID from its client id: 0x + the 16 bytes in [guid]::ToByteArray() order. #>
|    param([Parameter(Mandatory)][string]$ClientId)
|    '0x' + ((([guid]$ClientId).ToByteArray() | ForEach-Object { $_.ToString('X2') }) -join '')
|}
|
|function Get-SIDbInitProp {
|    <# PURE. A nested property (PSCustomObject, hashtable or DataRow); $null when any step is missing. #>
|    param($Object, [string[]]$Names)
|    $o = $Object
|    foreach ($n in $Names) {
|        if ($null -eq $o) { return $null }
|        if ($o -is [System.Data.DataRow]) { if ($o.Table.Columns.Contains($n)) { $o = $o[$n]; if ($o -is [System.DBNull]) { $o = $null } } else { return $null }; continue }
|        if ($o -is [System.Collections.IDictionary]) { if ($o.Contains($n)) { $o = $o[$n] } else { return $null }; continue }
|        $p = $o.PSObject.Properties[$n]
|        if (-not $p) { return $null }
|        $o = $p.Value
|    }
|    $o
|}
|
|# =====================================================================================================================
|#  THE JOB'S SIDE (container/Start-SIDbInit.ps1)
|# =====================================================================================================================
|
|function Read-SIDbInitInput {
|    <#
|        PURE. The job's inputs (its environment; -Env first, then the process), checked. Returns @{ Ok; Reason; Server;
|        Database; LedgerDatabase; MiClientId; Principals (@{ Component; Name; ClientId }); Support (@{ ClientId; UserName } or
|        $null); SignedGrants; EngineRoleOnly; Run; By }. Refused: a principal list that is not JSON, an unknown component, a
|        name that is not safe, a client id that is not a GUID, two entries for one component, no engine identity.
|          SI_DBINIT_SERVER / SI_DBINIT_DATABASE / SI_DBINIT_LEDGER_DATABASE   the server and the databases
|          SI_DBINIT_MI_CLIENT_ID      the job's own identity (the token is asked for THIS identity)
|          SI_DBINIT_PRINCIPALS        JSON [{ "component": "engine", "name": "id-si-engine", "clientId": "<guid>" }, ...]
|          SI_DBINIT_SIGNED_GRANTS     1 = the signed grant procedure model (SI_Setup_SignedGrantProcedure)
|          SI_DBINIT_ENGINE_ROLE_ONLY  1 = the engine gets its role si_engine only (SI_Setup_EngineLeastPrivilege)
|          per execution: SI_DBINIT_RUN (the caller's run id), SI_DBINIT_BY (installer | updater | support),
|                         SI_DBINIT_SUPPORT ('<client id>|<user name>': the Invardia Support app -- installer / support only)
|                         SI_DBINIT_SUPPORT_STANDING_OFF ('<client id>': #1151 SEC-01 -- the updater names the recorded Support
|                         app; the job takes its STANDING db_owner off in each product database where the just-in-time path
|                         reads back in the same batch, Get-SISupportStandingOffSql; never the group, never a user)
|                         SI_DBINIT_STEPS (all | grants: users, role memberships and grants only -- no procedure, schema or
|                         database setting is created or changed, so it may run beside a pipeline run; anything else = all)
|    #>
|    param([hashtable]$Env = @{})
|    $e = { param($k) if ($Env.ContainsKey($k)) { [string]$Env[$k] } else { [string][Environment]::GetEnvironmentVariable($k) } }
|    $no = { param($r) [pscustomobject]@{ Ok = $false; Reason = $r } }
|    $names = Get-SIDbInitNames
|    $server = (& $e 'SI_DBINIT_SERVER').Trim()
|    if ($server -notmatch '^[A-Za-z0-9][A-Za-z0-9.-]{1,253}$') { return (& $no 'SI_DBINIT_SERVER is not a server name') }
|    $db = (& $e 'SI_DBINIT_DATABASE').Trim(); if (-not $db) { $db = $names.ProDatabase }
|    $ledger = (& $e 'SI_DBINIT_LEDGER_DATABASE').Trim()
|    foreach ($d in @($db, $ledger) | Where-Object { $_ }) { if ($d -notmatch '^[A-Za-z0-9_.-]{1,128}$') { return (& $no ("the database name '{0}' is not safe" -f $d)) } }
|    $mi = (& $e 'SI_DBINIT_MI_CLIENT_ID').Trim()
|    $g = [guid]::Empty
|    if ($mi -and -not [guid]::TryParse($mi, [ref]$g)) { return (& $no 'SI_DBINIT_MI_CLIENT_ID is not a client id') }
|    $json = (& $e 'SI_DBINIT_PRINCIPALS').Trim()
|    if (-not $json) { return (& $no 'SI_DBINIT_PRINCIPALS is not set') }
|    $list = $null
|    try { $list = @($json | ConvertFrom-Json -ErrorAction Stop) } catch { return (& $no 'SI_DBINIT_PRINCIPALS is not JSON') }
|    $known = Get-SIDbInitComponents
|    $p = New-Object System.Collections.Generic.List[object]
|    foreach ($x in $list) {
|        if ($null -eq $x) { continue }
|        $c = ([string](Get-SIDbInitProp $x @('component'))).Trim().ToLowerInvariant()
|        $n = ([string](Get-SIDbInitProp $x @('name'))).Trim()
|        $cid = ([string](Get-SIDbInitProp $x @('clientId'))).Trim()
|        if ($known -notcontains $c) { return (& $no ("unknown component '{0}' (known: {1})" -f $c, ($known -join ', '))) }
|        if ($n -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$') { return (& $no ("the {0} identity's name '{1}' is not safe" -f $c, $n)) }
|        $g = [guid]::Empty
|        if (-not [guid]::TryParse($cid, [ref]$g) -or $g -eq [guid]::Empty) { return (& $no ("the client id of the {0} identity is not a GUID" -f $c)) }
|        if (@($p | Where-Object { $_.Component -eq $c }).Count) { return (& $no ("the {0} identity is listed twice" -f $c)) }
|        $p.Add([pscustomobject]@{ Component = $c; Name = $n; ClientId = $g.ToString() })
|    }
|    if (-not @($p | Where-Object { $_.Component -eq 'engine' }).Count) { return (& $no 'the principal list names no engine identity') }
|    $sup = $null
|    $s = (& $e 'SI_DBINIT_SUPPORT').Trim()
|    if ($s) {
|        $parts = $s.Split('|')
|        $g = [guid]::Empty
|        if ($parts.Count -ne 2 -or -not [guid]::TryParse($parts[0], [ref]$g) -or $parts[1] -notmatch '^[A-Za-z0-9][A-Za-z0-9 ._@-]{0,127}$') { return (& $no 'SI_DBINIT_SUPPORT is not "<client id>|<user name>"') }
|        $sup = [pscustomobject]@{ ClientId = $g.ToString(); UserName = $parts[1] }
|    }
|    # #1151 SEC-01: the Support app whose STANDING db_owner the job takes off (where the just-in-time path reads back)
|    $off = (& $e 'SI_DBINIT_SUPPORT_STANDING_OFF').Trim()
|    if ($off) { $g = [guid]::Empty; if (-not [guid]::TryParse($off, [ref]$g) -or $g -eq [guid]::Empty) { return (& $no 'SI_DBINIT_SUPPORT_STANDING_OFF is not a client id') }; $off = $g.ToString() }
|    $run = (& $e 'SI_DBINIT_RUN').Trim(); if ($run -notmatch '^[A-Za-z0-9-]{1,40}$') { $run = '' }
|    $by = (& $e 'SI_DBINIT_BY').Trim().ToLowerInvariant(); if ($by -notin 'installer', 'updater', 'support') { $by = 'job' }
|    $on = { param($k) (& $e $k).Trim() -match '^(?i)(1|true|yes|on)$' }
|    $steps = if ((& $e 'SI_DBINIT_STEPS').Trim() -ieq 'grants') { 'grants' } else { 'all' }
|    # THE IDENTITY MOVE (framework §5.5 names; setup\_shared\SI-IdentityMove.ps1), per execution only:
|    #   SI_DBINIT_MOVES  [{ "component": "web", "from": "<old client id>", "to": "<new client id>", "toName": "id-si-web" }]
|    #   SI_DBINIT_DROPS  [{ "component": "web", "clientId": "<old>", "keepClientId": "<new>", "keepName": "id-si-web" }]
|    $mv = Read-SIDbInitMoveList -Json (& $e 'SI_DBINIT_MOVES') -Kind moves -MiClientId $mi -Support $sup
|    if (-not $mv.Ok) { return (& $no $mv.Reason) }
|    $dr = Read-SIDbInitMoveList -Json (& $e 'SI_DBINIT_DROPS') -Kind drops -MiClientId $mi -Support $sup -InUse @($p | ForEach-Object { $_.ClientId })
|    if (-not $dr.Ok) { return (& $no $dr.Reason) }
|    [pscustomobject]@{ Ok = $true; Reason = ''; Server = $server; Database = $db; LedgerDatabase = $ledger; MiClientId = $mi; Principals = $p.ToArray()
|                       Support = $sup; SignedGrants = (& $on 'SI_DBINIT_SIGNED_GRANTS'); EngineRoleOnly = (& $on 'SI_DBINIT_ENGINE_ROLE_ONLY'); Run = $run; By = $by; Steps = $steps
|                       Moves = @($mv.Items); Drops = @($dr.Items); StandingOff = $off }
|}
|
|function Read-SIDbInitMoveList {
|    <#
|        PURE. One identity-move list of the job's input (SI_DBINIT_MOVES / SI_DBINIT_DROPS), checked. '' = none. Refused: not
|        JSON, an unknown component, a client id that is not a GUID, an unsafe name, a move onto itself -- and a DROP of the
|        job's own identity, of the Invardia Support app, of an identity an app or job of the install still signs in as
|        (-InUse: the principal list), or one whose kept identity is the same. Returns @{ Ok; Reason; Items }.
|    #>
|    param([AllowEmptyString()][AllowNull()][string]$Json, [Parameter(Mandatory)][ValidateSet('moves', 'drops')][string]$Kind, [string]$MiClientId = '', $Support = $null, [string[]]$InUse = @())
|    $ok = { param($items) [pscustomobject]@{ Ok = $true; Reason = ''; Items = @($items) } }
|    $no = { param($r) [pscustomobject]@{ Ok = $false; Reason = $r; Items = @() } }
|    $var = if ($Kind -eq 'moves') { 'SI_DBINIT_MOVES' } else { 'SI_DBINIT_DROPS' }
|    if (-not "$Json".Trim()) { return (& $ok @()) }
|    $list = $null
|    try { $list = @("$Json" | ConvertFrom-Json -ErrorAction Stop) } catch { return (& $no ('{0} is not JSON' -f $var)) }
|    $guid = { param($v) $g = [guid]::Empty; if ([guid]::TryParse("$v".Trim(), [ref]$g) -and $g -ne [guid]::Empty) { $g.ToString() } else { '' } }
|    $known = Get-SIDbInitComponents
|    $used = @($InUse | Where-Object { $_ } | ForEach-Object { "$_".ToLowerInvariant() })
|    $out = New-Object System.Collections.Generic.List[object]
|    foreach ($x in $list) {
|        if ($null -eq $x) { continue }
|        $c = ([string](Get-SIDbInitProp $x @('component'))).Trim().ToLowerInvariant()
|        if ($known -notcontains $c) { return (& $no ("{0}: unknown component '{1}'" -f $var, $c)) }
|        if ($Kind -eq 'moves') {
|            $f = & $guid (Get-SIDbInitProp $x @('from')); $t = & $guid (Get-SIDbInitProp $x @('to')); $n = ([string](Get-SIDbInitProp $x @('toName'))).Trim()
|            if (-not $f -or -not $t) { return (& $no ('{0}: the {1} move needs the old and the new client id' -f $var, $c)) }
|            if ($f -eq $t) { return (& $no ('{0}: the {1} move names the same identity twice' -f $var, $c)) }
|            if ($n -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{1,127}$') { return (& $no ("{0}: the {1} identity's name '{2}' is not safe" -f $var, $c, $n)) }
|            $out.Add([pscustomobject]@{ Component = $c; From = $f; To = $t; ToName = $n })
|        } else {
|            $d = & $guid (Get-SIDbInitProp $x @('clientId')); $k = & $guid (Get-SIDbInitProp $x @('keepClientId')); $n = ([string](Get-SIDbInitProp $x @('keepName'))).Trim()
|            if (-not $d -or -not $k) { return (& $no ('{0}: the {1} drop needs the old and the kept client id' -f $var, $c)) }
|            if ($d -eq $k) { return (& $no ('{0}: the {1} drop would drop the identity it keeps' -f $var, $c)) }
|            if ($n -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{1,127}$') { return (& $no ("{0}: the kept {1} identity's name '{2}' is not safe" -f $var, $c, $n)) }
|            if ($MiClientId -and $d -ieq $MiClientId) { return (& $no ('{0}: the job never drops its own identity' -f $var)) }
|            if ($Support -and $d -ieq [string]$Support.ClientId) { return (& $no ('{0}: the job never drops the Invardia Support app' -f $var)) }
|            if ($used -contains $d.ToLowerInvariant()) { return (& $no ('{0}: the {1} identity {2} is still what an app or job of the install signs in as -- it is not dropped' -f $var, $c, $d)) }
|            $out.Add([pscustomobject]@{ Component = $c; ClientId = $d; KeepClientId = $k; KeepName = $n })
|        }
|    }
|    & $ok $out.ToArray()
|}
|
|function Invoke-SIDbInitMoves {
|    <#
|        THE IDENTITY MOVE's database side, as the SQL admin (setup\_shared\SI-IdentityMoveSql.ps1 -- the move's own builders):
|          moves  per database (-Databases: the Pro database, the identity ledger, every other product database): the old
|                 user's roles and explicit permissions copied to the new identity's user (made from its client id), then
|                 READ AGAIN -- the copy must be empty. A right the builders cannot copy is a problem, never skipped.
|          drops  per database: the old user dropped ONLY where a read made just before shows the kept identity's user
|                 holding every role and permission of it (Test-SIIdentityMoveSqlCovered); then read again -- gone.
|        Returns @{ Problems; Lines; States (component -> ok | none | dropped | failed) }. -Sql: the job's seam.
|    #>
|    param([Parameter(Mandatory)]$DbInput, [Parameter(Mandatory)][scriptblock]$Sql, [string[]]$Databases = @())
|    $problems = New-Object System.Collections.Generic.List[string]; $lines = New-Object System.Collections.Generic.List[string]; $states = @{}
|    $rowsOf = { param($d, $o, $n) @(& $Sql $d (Get-SIIdentityMoveSqlReadSql -OldClientId $o -NewClientId $n) @{} 'rows' | ForEach-Object { $_ } | Where-Object { $null -ne $_ }) }
|    $mark = { param($c, $v) if ($states[$c] -ne 'failed') { if ($v -eq 'failed' -or -not $states.ContainsKey($c) -or $states[$c] -eq 'none') { $states[$c] = $v } } }
|    if (-not (Get-Command -Name Get-SIIdentityMoveSqlCopy -ErrorAction SilentlyContinue)) {
|        foreach ($m in @($DbInput.Moves) + @($DbInput.Drops)) { if ($m) { $states[$m.Component] = 'failed' } }
|        if (@($DbInput.Moves).Count -or @($DbInput.Drops).Count) { $problems.Add('this package carries no identity move SQL (setup\_shared\SI-IdentityMoveSql.ps1)') }
|        return [pscustomobject]@{ Problems = $problems.ToArray(); Lines = $lines.ToArray(); States = $states }
|    }
|    foreach ($m in @($DbInput.Moves)) {
|        foreach ($d in @($Databases | Where-Object { $_ })) {
|            try {
|                $c = Get-SIIdentityMoveSqlCopy -Rows (& $rowsOf $d $m.From $m.To) -NewName $m.ToName -NewClientId $m.To
|                if (-not $c.OldUser) { & $mark $m.Component 'none'; $lines.Add(('{0}: the old {1} identity has no user here -- nothing to copy' -f $d, $m.Component)); continue }
|                if (@($c.Unsupported).Count) { & $mark $m.Component 'failed'; $problems.Add(('{0}: the {1} identity''s user holds a right the move cannot copy ({2}) -- nothing copied' -f $d, $m.Component, (@($c.Unsupported) -join '; '))); continue }
|                if ($c.Sql) { $null = & $Sql $d $c.Sql @{} 'nonquery'; $lines.Add(('done: {0}: {1} -> {2}: {3}' -f $d, $c.OldUser, $m.ToName, (@($c.Items) -join '; '))) }
|                $again = Get-SIIdentityMoveSqlCopy -Rows (& $rowsOf $d $m.From $m.To) -NewName $m.ToName -NewClientId $m.To
|                if ($again.Sql -or @($again.Unsupported).Count -or -not $again.NewUser) { & $mark $m.Component 'failed'; $problems.Add(('{0}: the {1} identity {2} does not read back holding every right of {3}' -f $d, $m.Component, $m.ToName, $c.OldUser)); continue }
|                & $mark $m.Component 'ok'
|                $lines.Add(('read back: {0}: {1} holds every role and permission of {2}' -f $d, $again.NewUser, $c.OldUser))
|            } catch { & $mark $m.Component 'failed'; $problems.Add(('{0}: the {1} move: {2}' -f $d, $m.Component, $_.Exception.Message)) }
|        }
|    }
|    foreach ($x in @($DbInput.Drops)) {
|        foreach ($d in @($Databases | Where-Object { $_ })) {
|            try {
|                $cov = Test-SIIdentityMoveSqlCovered -Rows (& $rowsOf $d $x.ClientId $x.KeepClientId) -KeepName $x.KeepName -KeepClientId $x.KeepClientId
|                if (-not $cov.OldUser) { & $mark $x.Component 'none'; continue }
|                if (-not $cov.Drop) { & $mark $x.Component 'failed'; $problems.Add(('{0}: KEPT: {1}' -f $d, $cov.Why)); continue }
|                $null = & $Sql $d (Get-SIIdentityMoveSqlDropSql -OldClientId $x.ClientId) @{} 'nonquery'
|                $gone = Get-SIIdentityMoveSqlCopy -Rows (& $rowsOf $d $x.ClientId $x.KeepClientId) -NewName $x.KeepName -NewClientId $x.KeepClientId
|                if ($gone.OldUser) { & $mark $x.Component 'failed'; $problems.Add(('{0}: the old {1} user {2} is still there after the drop' -f $d, $x.Component, $gone.OldUser)); continue }
|                & $mark $x.Component 'dropped'
|                $lines.Add(('done: {0}: the old {1} user {2} dropped ({3})' -f $d, $x.Component, $cov.OldUser, $cov.Why))
|            } catch { & $mark $x.Component 'failed'; $problems.Add(('{0}: the {1} drop: {2}' -f $d, $x.Component, $_.Exception.Message)) }
|        }
|    }
|    [pscustomobject]@{ Problems = $problems.ToArray(); Lines = $lines.ToArray(); States = $states }
|}
|
|function New-SIDbInitMovesRecordValue {
|    <# PURE. The identity move's own result row (cfg.InstallState 'DbJobMoves', <= 400 characters): the run and each
|       component's state. #>
|    param([string]$Run = '', [hashtable]$States = @{}, [datetime]$NowUtc = [datetime]::UtcNow)
|    $o = [ordered]@{ run = $Run; at = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture); c = [ordered]@{} }
|    foreach ($k in @($States.Keys | Sort-Object)) { $o.c[[string]$k] = [string]$States[$k] }
|    ConvertTo-Json -InputObject $o -Compress -Depth 4
|}
|
|function Get-SIDbInitUsersSql {
|    <# PURE. READ ONLY: the database's Entra users with their client ids and roles (one row per role; RoleName NULL = none). #>
|@'
|SELECT p.name AS Name, LOWER(CONVERT(varchar(36), CONVERT(uniqueidentifier, p.sid))) AS ClientId, r.name AS RoleName
|FROM sys.database_principals AS p
|LEFT JOIN sys.database_role_members AS m ON m.member_principal_id = p.principal_id
|LEFT JOIN sys.database_principals AS r ON r.principal_id = m.role_principal_id
|WHERE p.[type] IN ('E', 'X') AND DATALENGTH(p.sid) = 16;
|'@
|}
|
|function ConvertFrom-SIDbInitUsers {
|    <# PURE. Rows of Get-SIDbInitUsersSql -> @{ <client id lower> = @{ Name; Roles[] } }. #>
|    param([object[]]$Rows = @())
|    $h = @{}
|    foreach ($r in @($Rows | Where-Object { $null -ne $_ })) {
|        $cid = ([string](Get-SIDbInitProp $r @('ClientId'))).Trim().ToLowerInvariant()
|        if (-not $cid) { continue }
|        if (-not $h.ContainsKey($cid)) { $h[$cid] = [pscustomobject]@{ Name = [string](Get-SIDbInitProp $r @('Name')); Roles = (New-Object System.Collections.Generic.List[string]) } }
|        $role = [string](Get-SIDbInitProp $r @('RoleName'))
|        if ($role -and -not $h[$cid].Roles.Contains($role)) { $h[$cid].Roles.Add($role) }
|    }
|    $h
|}
|
|function Get-SIDbInitLedgerEngineSql {
|    <# PURE. The identity ledger (its own database): the engine identity's contained user by its client id (reused whatever
|       its name) with db_datareader + db_datawriter -- what the guided install's schema step gives it. #>
|    param([Parameter(Mandatory)][string]$UserName, [Parameter(Mandatory)][string]$ClientId)
|    $sid = Get-SIDbInitSid -ClientId $ClientId
|    $n = $UserName.Replace(']', ']]'); $q = $UserName.Replace("'", "''")
|    @"
|DECLARE @n sysname = (SELECT name FROM sys.database_principals WHERE sid = $sid);
|IF @n IS NULL BEGIN CREATE USER [$n] WITH SID = $sid, TYPE = E; SET @n = N'$q'; END
|DECLARE @s nvarchar(400);
|SET @s = N'ALTER ROLE db_datareader ADD MEMBER ' + QUOTENAME(@n); EXEC (@s);
|SET @s = N'ALTER ROLE db_datawriter ADD MEMBER ' + QUOTENAME(@n); EXEC (@s);
|"@
|}
|
|function Get-SIDbInitDatabasesSql {
|    <# PURE. READ ONLY, run in master (the job is the server's administrator through the group): the server's user databases. #>
|    'SELECT name AS Name FROM sys.databases WHERE database_id > 4 AND name <> N''master'' ORDER BY name;'
|}
|
|function Get-SIDbInitSupportDbSql {
|    <#
|        PURE. #1021 (found live at an install 2026-11-04): the support grant's procedures are in EVERY product database (the
|        Pro database, the identity ledger, the data database) and each checks ITS OWN cfg.SupportConsent. So in a product
|        database OTHER than the Pro one -- only where the support grant's tables are (cfg.SupportConsent) -- the job makes what
|        Move-SIEngineToLeastPrivilege makes in the Pro database: the role si_engine, the engine's user (by its client id) in
|        it and EXECUTE on cfg.SupportGrantOpen / Close / Sweep / Status; and for the updater (it mirrors the Pro database's
|        consent there): the role si_updater, its user in it, and SELECT / INSERT / UPDATE / DELETE on cfg.SupportConsent (the
|        consent trigger lets si_updater write only a row from the Invardia portal, or remove it). Idempotent; only adds.
|    #>
|    param([Parameter(Mandatory)][string]$EngineUser, [Parameter(Mandatory)][string]$EngineClientId, [string]$UpdaterUser = '', [string]$UpdaterClientId = '')
|    $u = { param($var, $name, $cid, $role)
|        $sid = Get-SIDbInitSid -ClientId $cid; $n = $name.Replace(']', ']]').Replace("'", "''"); $q = $name.Replace("'", "''")
|        @"
|    SET $var = (SELECT TOP (1) name FROM sys.database_principals WHERE sid = $sid AND principal_id > 4);
|    IF $var IS NULL BEGIN EXEC (N'CREATE USER [$n] WITH SID = $sid, TYPE = E'); SET $var = N'$q'; END
|    IF ISNULL(IS_ROLEMEMBER(N'$role', $var), 0) = 0 BEGIN SET @s = N'ALTER ROLE [$role] ADD MEMBER ' + QUOTENAME($var); EXEC (@s); END
|"@ }
|    $l = New-Object System.Collections.Generic.List[string]
|    $l.Add("IF OBJECT_ID(N'cfg.SupportConsent') IS NOT NULL")
|    $l.Add('BEGIN')
|    $l.Add('    DECLARE @s nvarchar(400), @e sysname, @u sysname;')
|    $l.Add("    IF DATABASE_PRINCIPAL_ID(N'si_engine') IS NULL EXEC (N'CREATE ROLE [si_engine] AUTHORIZATION [dbo]');")
|    $l.Add((& $u '@e' $EngineUser $EngineClientId 'si_engine').TrimEnd())
|    foreach ($p in 'Open', 'Close', 'Sweep', 'Status') { $l.Add("    IF OBJECT_ID(N'cfg.SupportGrant$p') IS NOT NULL GRANT EXECUTE ON OBJECT::cfg.SupportGrant$p TO [si_engine];") }
|    if ($UpdaterUser -and $UpdaterClientId) {
|        $l.Add("    IF DATABASE_PRINCIPAL_ID(N'si_updater') IS NULL EXEC (N'CREATE ROLE [si_updater] AUTHORIZATION [dbo]');")
|        $l.Add((& $u '@u' $UpdaterUser $UpdaterClientId 'si_updater').TrimEnd())
|        $l.Add('    GRANT SELECT, INSERT, UPDATE, DELETE ON OBJECT::cfg.SupportConsent TO [si_updater];')
|    }
|    $l.Add('END')
|    $l.ToArray() -join "`n"
|}
|
|function Get-SIDbInitSupportDbStateSql {
|    <# PURE. READ ONLY, one row: the support grant's table here, the engine's user in si_engine with EXECUTE on the four
|       procedures that are here, the updater's user in si_updater with its four rights on cfg.SupportConsent. #>
|    param([Parameter(Mandatory)][string]$EngineClientId, [string]$UpdaterClientId = '')
|    $es = Get-SIDbInitSid -ClientId $EngineClientId
|    $us = if ($UpdaterClientId) { Get-SIDbInitSid -ClientId $UpdaterClientId } else { 'NULL' }
|    @"
|DECLARE @e sysname = (SELECT TOP (1) name FROM sys.database_principals WHERE sid = $es), @u sysname = (SELECT TOP (1) name FROM sys.database_principals WHERE sid = $us);
|SELECT CASE WHEN OBJECT_ID(N'cfg.SupportConsent') IS NULL THEN 0 ELSE 1 END AS ConsentTable,
|       CASE WHEN @e IS NULL THEN 0 ELSE ISNULL(IS_ROLEMEMBER(N'si_engine', @e), 0) END AS EngineInRole,
|       (SELECT COUNT(*) FROM (VALUES (N'cfg.SupportGrantOpen'), (N'cfg.SupportGrantClose'), (N'cfg.SupportGrantSweep'), (N'cfg.SupportGrantStatus')) AS v(n) WHERE OBJECT_ID(v.n) IS NOT NULL) AS Procedures,
|       (SELECT COUNT(*) FROM (VALUES (N'cfg.SupportGrantOpen'), (N'cfg.SupportGrantClose'), (N'cfg.SupportGrantSweep'), (N'cfg.SupportGrantStatus')) AS v(n)
|         JOIN sys.database_permissions AS dp ON dp.class = 1 AND dp.major_id = OBJECT_ID(v.n) AND dp.permission_name = N'EXECUTE' AND dp.[state] IN ('G', 'W')
|         WHERE dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'si_engine')) AS EngineExecute,
|       CASE WHEN @u IS NULL THEN 0 ELSE ISNULL(IS_ROLEMEMBER(N'si_updater', @u), 0) END AS UpdaterInRole,
|       (SELECT COUNT(DISTINCT dp.permission_name) FROM sys.database_permissions AS dp WHERE dp.class = 1 AND dp.major_id = OBJECT_ID(N'cfg.SupportConsent')
|         AND dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'si_updater') AND dp.[state] IN ('G', 'W') AND dp.permission_name IN (N'SELECT', N'INSERT', N'UPDATE', N'DELETE')) AS UpdaterConsentRights;
|"@
|}
|
|function Test-SIDbInitSupportDbState {
|    <# PURE. The row of Get-SIDbInitSupportDbStateSql -> @{ Applies; Problems[] }. A database without the support grant's
|       table is not one this applies to. -Updater: the updater's part was asked for. #>
|    param($Row, [bool]$Updater = $true)
|    $i = { param($k) $v = Get-SIDbInitProp $Row @($k); $n = 0; [void][int]::TryParse("$v", [ref]$n); $n }
|    $p = New-Object System.Collections.Generic.List[string]
|    if ((& $i 'ConsentTable') -ne 1) { return [pscustomobject]@{ Applies = $false; Problems = @() } }
|    if ((& $i 'EngineInRole') -ne 1) { $p.Add('the engine''s user is not in si_engine') }
|    if ((& $i 'EngineExecute') -lt (& $i 'Procedures')) { $p.Add(('si_engine may EXECUTE {0} of the {1} support grant procedures' -f (& $i 'EngineExecute'), (& $i 'Procedures'))) }
|    if ($Updater) {
|        if ((& $i 'UpdaterInRole') -ne 1) { $p.Add('the updater''s user is not in si_updater') }
|        if ((& $i 'UpdaterConsentRights') -lt 4) { $p.Add('si_updater may not read and write cfg.SupportConsent') }
|    }
|    [pscustomobject]@{ Applies = $true; Problems = $p.ToArray() }
|}
|
|function Get-SIDbInitConsentReadSql {
|    <# PURE. READ ONLY: the consent row (Level, Source, ConsentedBy, AppId) -- none when the table or the row is not there. #>
|    "IF OBJECT_ID(N'cfg.SupportConsent') IS NOT NULL SELECT [Level], Source, ConsentedBy, CONVERT(nvarchar(36), AppId) AS AppId FROM cfg.SupportConsent WHERE Id = 1;"
|}
|
|function Get-SIDbInitConsentCopySql {
|    <# PURE. The Pro database's consent row copied into this database as it is (@AppId, @Level, @Source, @By) -- run by the
|       job as the database's owner (the trigger lets the owner write any row); only where the table is. #>
|@'
|IF OBJECT_ID(N'cfg.SupportConsent') IS NOT NULL
|BEGIN
|    IF NOT EXISTS (SELECT 1 FROM cfg.SupportConsent WHERE Id = 1)
|        INSERT cfg.SupportConsent (Id, AppId, [Level], Source, ConsentedBy) VALUES (1, CONVERT(uniqueidentifier, @AppId), @Level, @Source, LEFT(@By, 256));
|    ELSE IF NOT EXISTS (SELECT 1 FROM cfg.SupportConsent WHERE Id = 1 AND AppId = CONVERT(uniqueidentifier, @AppId) AND [Level] = @Level AND Source = @Source AND ConsentedBy = LEFT(@By, 256))
|        UPDATE cfg.SupportConsent SET AppId = CONVERT(uniqueidentifier, @AppId), [Level] = @Level, Source = @Source, ConsentedBy = LEFT(@By, 256), ConsentedUtc = SYSUTCDATETIME() WHERE Id = 1;
|END
|'@
|}
|
|function Get-SIDbInitDatabasesRecordSql {
|    <# PURE. The product databases with the support grant's table, OTHER than the Pro one (cfg.InstallState
|       'SupportGrantDatabases', @Value = 'a;b', <= 400) -- the updater mirrors the Pro database's consent into them. #>
|@'
|IF OBJECT_ID(N'cfg.InstallState') IS NOT NULL
|BEGIN
|    IF EXISTS (SELECT 1 FROM cfg.InstallState WHERE Name = N'SupportGrantDatabases')
|        UPDATE cfg.InstallState SET Value = LEFT(@Value, 400), UpdatedAt = SYSUTCDATETIME(), UpdatedBy = N'caj-si-dbinit' WHERE Name = N'SupportGrantDatabases';
|    ELSE INSERT cfg.InstallState (Name, Value, UpdatedBy) VALUES (N'SupportGrantDatabases', LEFT(@Value, 400), N'caj-si-dbinit');
|END
|'@
|}
|
|function Get-SIDbInitStatsAsyncSql {
|    <# PURE. The database's setting that a stale statistic is updated in the background; idempotent (on already = a read only).
|       A lock that does not come within 10 seconds is an error the job says as a warning; the next update tries again. #>
|    @'
|IF (SELECT d.is_auto_update_stats_async_on FROM sys.databases AS d WHERE d.database_id = DB_ID()) = 0
|BEGIN
|    SET LOCK_TIMEOUT 10000;
|    ALTER DATABASE CURRENT SET AUTO_UPDATE_STATISTICS_ASYNC ON;
|    SET LOCK_TIMEOUT -1;
|END
|'@
|}
|
|function Get-SIDbInitSupportUserReplaceSql {
|    <#
|        PURE. support-user-replace (Invardia, framework owner, 2026-11-05; found live at an install: the Support app's user
|        was made from ANOTHER tenant's Support app client id, and a run with the right id could not CREATE it -- the name
|        was taken). Drops ONE user, and only when ALL hold: it carries the Support app's user NAME, it is an Entra user
|        (-PrincipalTypes; E / X -- 'S' only for the offline real-SQL test, which has no Entra), its SID is NOT the SID of
|        -ClientId (this run's Support app), and NO user carries the right SID under another name. Its role memberships go
|        with it. Any other case touches nothing. Ends with one row: OldSid (the wrong SID as hex, NULL = none), Dropped.
|    #>
|    param([Parameter(Mandatory)][string]$UserName, [Parameter(Mandatory)][string]$ClientId, [ValidateSet('E', 'X', 'S')][string[]]$PrincipalTypes = @('E', 'X'))
|    $sid = Get-SIDbInitSid -ClientId $ClientId
|    if ($UserName -notmatch '^[A-Za-z0-9][A-Za-z0-9 ._@-]{0,127}$') { throw ("the Support app's user name '{0}' is not safe" -f $UserName) }
|    $q = $UserName.Replace("'", "''")
|    $types = (@($PrincipalTypes | Select-Object -Unique | ForEach-Object { "'$_'" })) -join ', '
|    @"
|DECLARE @old varbinary(85) = (SELECT TOP (1) sid FROM sys.database_principals WHERE name = N'$q' AND principal_id > 4 AND [type] IN ($types) AND sid <> $sid);
|DECLARE @drop nvarchar(400) = N'DROP USER ' + QUOTENAME(N'$q');
|IF @old IS NOT NULL AND NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE sid = $sid AND principal_id > 4)
|    EXEC (@drop);
|SELECT CONVERT(varchar(70), @old, 1) AS OldSid, CASE WHEN @old IS NOT NULL AND DATABASE_PRINCIPAL_ID(N'$q') IS NULL THEN 1 ELSE 0 END AS Dropped;
|"@
|}
|
|function Get-SIDbInitPlan {
|    <#
|        PURE apart from Get-Command (a builder a package does not carry is left out, said in Skipped). The batches the job
|        runs, in order, each @{ Step; Database; Name; Sql; Params; Required }. -Users / -LedgerUsers: ConvertFrom-SIDbInitUsers
|        of each database BEFORE (a user that is there under another name is used by that name). -ProcedureInstalled: the signed
|        grant procedure is in the Pro database already (it is then kept current also with the switch off). -Consent: the Pro
|        database's support consent ('<level>|<source>', '' = none). A batch with Required = $false that fails is a warning.
|    #>
|    param([Parameter(Mandatory)]$DbInput, [hashtable]$Users = @{}, [hashtable]$LedgerUsers = @{}, [bool]$ProcedureInstalled = $false, [string]$Consent = '',
|          # #1021: the product databases OTHER than the Pro one (the ledger, the data database) and the Pro database's consent row
|          [string[]]$SupportDatabases = @(), $ProConsent = $null)
|    $b = New-Object System.Collections.Generic.List[object]
|    $skipped = New-Object System.Collections.Generic.List[string]
|    $pro = $DbInput.Database; $led = $DbInput.LedgerDatabase
|    $has = { param($f) [bool](Get-Command -Name $f -CommandType Function -ErrorAction SilentlyContinue) }
|    $add = { param($step, $dbn, $name, $sql, $params, $req) $b.Add([pscustomobject]@{ Step = $step; Database = $dbn; Name = $name; Sql = $sql; Params = $(if ($params) { $params } else { @{} }); Required = [bool]$req }) }
|    $of = { param($c) @($DbInput.Principals | Where-Object { $_.Component -eq $c })[0] }
|    $nameIn = { param($users, $p) $k = $p.ClientId.ToLowerInvariant(); if ($users.ContainsKey($k) -and $users[$k].Name) { $users[$k].Name } else { $p.Name } }
|
|    $eng = & $of 'engine'
|    if (& $has 'Get-SIEngineDatabaseAccessSql') {
|        & $add 'engine' $pro ('the engine identity {0}: its user, the role si_engine and its grants{1}' -f $eng.Name, $(if ($DbInput.EngineRoleOnly) { ' (the role only)' } else { ' (and db_datareader + db_datawriter)' })) `
|            (Get-SIEngineDatabaseAccessSql -UserName $eng.Name -ClientId $eng.ClientId -KeepBroadRoles:(-not $DbInput.EngineRoleOnly)) $null $true
|    } else { $skipped.Add('engine (this package has no engine grant list)') }
|    if (& $has 'Get-SIEngineDatabaseGrantSql') { & $add 'engine-load' $pro 'the engine role''s read right on the database''s own load' (Get-SIEngineDatabaseGrantSql) $null $false }
|
|    $upd = & $of 'updater'
|    $procWanted = $false
|    if ($upd) {
|        if (& $has 'Get-SIUpdaterDatabaseAccessSql') {
|            & $add 'updater' $pro ('the updater identity {0}: its user, db_datareader, db_datawriter, db_ddladmin{1}' -f $upd.Name, $(if ($DbInput.SignedGrants) { '' } else { ', db_securityadmin' })) `
|                (Get-SIUpdaterDatabaseAccessSql -UserName $upd.Name -ClientId $upd.ClientId -NoSecurityAdmin:([bool]$DbInput.SignedGrants)) $null $true
|        } else { $skipped.Add('updater (this package has no updater grant list)') }
|        $procWanted = ([bool]$DbInput.SignedGrants -or $ProcedureInstalled) -and (& $has 'Get-SIGrantProcedureAdminSql')
|        if ($procWanted) {
|            $un = & $nameIn $Users $upd
|            foreach ($x in @(Get-SIGrantProcedureAdminSql -UpdaterUser $un)) { & $add ('procedure-' + $x.Step) $pro ('the signed grant procedure: ' + $x.Purpose) $x.Sql $null $true }
|        }
|    }
|
|    foreach ($w in @(@{ C = 'web'; Writer = $true }, @{ C = 'mcp'; Writer = $false })) {
|        $p = & $of $w.C
|        if (-not $p) { continue }
|        if (& $has 'Get-SIManagementUserSql') {
|            $nm = & $nameIn $Users $p
|            & $add $w.C $pro ('the {0} identity {1}: its user, db_datareader and its grants' -f $(if ($w.Writer) { 'web app' } else { 'MCP server' }), $nm) `
|                (Get-SIManagementUserSql -Identity ([pscustomobject]@{ Name = $nm; ClientId = $p.ClientId }) -Writer:$w.Writer) $null $true
|        } else { $skipped.Add(('{0} (this package has no web app grant list)' -f $w.C)) }
|    }
|    $web = & $of 'web'
|    if ($web -and (& $has 'Get-SISigninStoreSql')) {
|        foreach ($a in 'sql-user', 'sql-schema', 'sql-grant') {
|            & $add ('signin-' + $a.Substring(4)) $pro ('the sign-in front''s store: ' + $(switch ($a) { 'sql-user' { 'the web identity''s user' } 'sql-schema' { 'the schema signin owned by the web identity' } default { 'CREATE TABLE for the web identity' } })) `
|                (Get-SISigninStoreSql -Action $a) @{ ClientId = $web.ClientId; UserName = (& $nameIn $Users $web) } $true
|        }
|    }
|    $tag = & $of 'tagging'
|    if ($tag) {
|        if (& $has 'Get-SITaggingDatabaseAccessSql') {
|            & $add 'tagging' $pro ('asset tagging''s identity {0}: its user, db_datareader, INSERT on the audit trail' -f $tag.Name) (Get-SITaggingDatabaseAccessSql -UserName $tag.Name -ClientId $tag.ClientId) $null $true
|        } else { $skipped.Add('tagging (this package has no tagging grant)') }
|    }
|    if ($led) { & $add 'ledger-engine' $led ('the identity ledger: the engine identity {0} reads and writes it' -f $eng.Name) (Get-SIDbInitLedgerEngineSql -UserName $eng.Name -ClientId $eng.ClientId) $null $true }
|
|    # 2026-11-05 (framework §12.27 SQL-STATS): every product database updates a stale statistic in the background, so a page read
|    # never waits for one. Only this job may change a database setting (the server's admin group); the update runs it on every
|    # update, so an existing install reaches what a new one has. Not required: a setting that cannot change now is a warning.
|    foreach ($d in @(@($pro) + @($(if ($led) { $led })) + @($SupportDatabases) | Where-Object { $_ } | Select-Object -Unique)) {
|        & $add 'stats-async' $d ('{0}: statistics updated in the background (a page never waits for one)' -f $d) (Get-SIDbInitStatsAsyncSql) $null $false
|    }
|
|    # the Invardia Support app: only when the caller names it (the install's Support setting, or a support repair) -- the
|    # update never touches it (owner 2026-10-18: Invardia repairs a missing part itself)
|    if ($DbInput.Support) {
|        $dbs = @($pro) + @($(if ($led) { $led }))
|        # support-user-replace (Invardia, framework owner, 2026-11-05): a user under the Support app's NAME whose SID is not
|        # the SID of THIS run's Support app (another tenant's Support app id typed by hand) blocks the CREATE below. Only
|        # then -- and only when no user carries the right SID under another name -- that one user is dropped (its role
|        # memberships go with it) and the next step makes the right one. Both SIDs are said in the job's lines.
|        if (& $has 'Get-SIDbInitSupportUserReplaceSql') {
|            $want = $DbInput.Support.ClientId.ToLowerInvariant()
|            foreach ($d in $dbs) {
|                $uu = if ($d -eq $pro) { $Users } else { $LedgerUsers }
|                if (-not $uu -or $uu.ContainsKey($want)) { continue }
|                $wrong = @($uu.Keys | Where-Object { $_ -ne $want -and [string]$uu[$_].Name -ieq $DbInput.Support.UserName })[0]
|                if (-not $wrong) { continue }
|                & $add 'support-user-replace' $d ('the Invardia Support app''s user {0} in {1} was made for client id {2} (SID {3}), not for this install''s Support app {4} (SID {5}): dropped with its role memberships, made again with the right SID by the next step' -f `
|                    $DbInput.Support.UserName, $d, $wrong, (Get-SIDbInitSid -ClientId $wrong), $DbInput.Support.ClientId, (Get-SIDbInitSid -ClientId $DbInput.Support.ClientId)) `
|                    (Get-SIDbInitSupportUserReplaceSql -UserName $DbInput.Support.UserName -ClientId $DbInput.Support.ClientId) $null $true
|            }
|        }
|        if (& $has 'Get-SISupportAppDatabaseAccessSql') {
|            foreach ($d in $dbs) { & $add 'support-user' $d ('the Invardia Support app''s own user ({0}) in {1}' -f $DbInput.Support.UserName, $d) (Get-SISupportAppDatabaseAccessSql -UserName $DbInput.Support.UserName -ClientId $DbInput.Support.ClientId) $null $true }
|        } else { $skipped.Add('support-user (this package has no Support app access)') }
|        # the install records WHICH Support app this is (cfg.InstallState 'SupportApp' = its client id: the heartbeat reports its
|        # access by it, the updater knows it as an owner of the web sign-in app) -- the same write the person-run path makes
|        # (setup\_shared\SI-SupportAppDatabase.ps1 Get-SISupportAppRecordSql: insert, or update when different), Pro database only
|        if (& $has 'Get-SISupportAppRecordSql') {
|            & $add 'support-record' $pro ('the install records the Invardia Support app {0} (cfg.InstallState SupportApp)' -f $DbInput.Support.ClientId) (Get-SISupportAppRecordSql -ClientId $DbInput.Support.ClientId -By 'the database setup job') $null $true
|        } else { $skipped.Add('support-record (this package does not record the Support app)') }
|        if (& $has 'Get-SISupportGrantAdminSteps') {
|            $lv = ''; $src = 'derived'
|            if ($Consent -and $Consent -ne '-') { $lv, $src = $Consent -split '\|', 2; if ($lv -notin 'troubleshoot', 'setup') { $lv = '' }; if ($src -ne 'customer') { $src = 'derived' } }
|            foreach ($d in $dbs) {
|                foreach ($x in @(Get-SISupportGrantAdminSteps -ClientId $DbInput.Support.ClientId -UserName $DbInput.Support.UserName -Level $lv -Source $src -By 'the database setup job')) {
|                    & $add ('support-grant-' + $x.Step) $d ('the support grant ({0}): {1}' -f $d, $x.Purpose) $x.Sql $null $true
|                }
|            }
|        } else { $skipped.Add('support-grant (this package has no support grant)') }
|    }
|
|    # #1021: every OTHER product database where the support grant is: the engine may run its procedures there, the updater
|    # may mirror the consent there; the Pro database's consent row copied as it is (the job is the owner there).
|    # AFTER the support grant steps (2026-11-06, seen at a customer install): this statement acts only where cfg.SupportConsent is, and a run
|    # that names the Support app makes that table in the identity ledger only above -- before, a first run left the engine
|    # outside si_engine there and its read-back failed until a second run.
|    $upd2 = & $of 'updater'
|    foreach ($d in @($SupportDatabases | Where-Object { $_ -and $_ -ne $pro } | Select-Object -Unique)) {
|        & $add 'support-db' $d ('{0}: the role si_engine with EXECUTE on the support grant procedures, {1} in it{2}' -f $d, $eng.Name, $(if ($upd2) { ('; si_updater with its rights on cfg.SupportConsent, {0} in it' -f $upd2.Name) } else { '' })) `
|            (Get-SIDbInitSupportDbSql -EngineUser $eng.Name -EngineClientId $eng.ClientId -UpdaterUser $(if ($upd2) { $upd2.Name } else { '' }) -UpdaterClientId $(if ($upd2) { $upd2.ClientId } else { '' })) $null $true
|        $pl = [string](Get-SIDbInitProp $ProConsent @('Level'))
|        if ($pl -in 'troubleshoot', 'setup') {
|            & $add 'consent-copy' $d ('{0}: the Pro database''s support consent ({1}) copied' -f $d, $pl) (Get-SIDbInitConsentCopySql) `
|                @{ AppId = [string](Get-SIDbInitProp $ProConsent @('AppId')); Level = $pl; Source = [string](Get-SIDbInitProp $ProConsent @('Source')); By = [string](Get-SIDbInitProp $ProConsent @('ConsentedBy')) } $true
|        }
|    }
|    # SI_DBINIT_STEPS=grants (Invardia 2026-11-06, framework §8.18): beside a running pipeline run only users, role memberships
|    # and grants -- the batches that create or change a procedure (the signed grant procedure, the support grant), a schema
|    # (signin-schema), a database setting (stats-async) or drop a user (support-user-replace) are left out and said
|    if ([string](Get-SIDbInitProp $DbInput @('Steps')) -eq 'grants') {
|        $ddl = '^(procedure-|support-grant-|signin-schema$|stats-async$|support-user-replace$)'
|        foreach ($x in @($b | Where-Object { $_.Step -match $ddl } | Select-Object -ExpandProperty Step -Unique)) { $skipped.Add(('{0} (grants only: it changes a procedure, a schema or a database setting)' -f $x)) }
|        $keep = @($b | Where-Object { $_.Step -notmatch $ddl })
|        return [pscustomobject]@{ Batches = $keep; Skipped = $skipped.ToArray(); Procedure = $false }
|    }
|    [pscustomobject]@{ Batches = $b.ToArray(); Skipped = $skipped.ToArray(); Procedure = [bool]$procWanted }
|}
|
|function Get-SIDbInitExpectations {
|    <# PURE. What the read-back must find: @{ Database; Component; Name; ClientId; Roles[] } per principal and database. #>
|    param([Parameter(Mandatory)]$DbInput, [bool]$Procedure = $false, [hashtable]$PlannedSteps = @{})
|    $x = New-Object System.Collections.Generic.List[object]
|    $pro = $DbInput.Database; $led = $DbInput.LedgerDatabase
|    foreach ($p in $DbInput.Principals) {
|        if (-not $PlannedSteps.ContainsKey($p.Component)) { continue }
|        $roles = switch ($p.Component) {
|            'engine'  { @('si_engine') + @($(if (-not $DbInput.EngineRoleOnly) { 'db_datareader', 'db_datawriter' })) }
|            'updater' { @('db_datareader', 'db_datawriter', 'db_ddladmin') + @($(if (-not $DbInput.SignedGrants) { 'db_securityadmin' })) + @($(if ($Procedure) { 'si_updater' })) }
|            default   { @('db_datareader') }
|        }
|        $x.Add([pscustomobject]@{ Database = $pro; Component = $p.Component; Name = $p.Name; ClientId = $p.ClientId; Roles = @($roles | Where-Object { $_ }) })
|        if ($p.Component -eq 'engine' -and $led -and $PlannedSteps.ContainsKey('ledger-engine')) { $x.Add([pscustomobject]@{ Database = $led; Component = 'engine'; Name = $p.Name; ClientId = $p.ClientId; Roles = @('db_datareader', 'db_datawriter') }) }
|    }
|    if ($DbInput.Support -and $PlannedSteps.ContainsKey('support-user')) {
|        foreach ($d in @($pro) + @($(if ($led) { $led }))) { $x.Add([pscustomobject]@{ Database = $d; Component = 'support'; Name = $DbInput.Support.UserName; ClientId = $DbInput.Support.ClientId; Roles = @('db_owner') }) }
|    }
|    $x.ToArray()
|}
|
|function Test-SIDbInitReadBack {
|    <#
|        PURE. The verdict of the read-back. -Users: database -> ConvertFrom-SIDbInitUsers AFTER the run. -Signin: the sign-in
|        store's state (ConvertFrom-SISigninStoreStateRow) or $null when not planned. -Procedure: Test-SIGrantProcedureReady's
|        answer or $null. -SupportGrant: database -> ConvertFrom-SISupportGrantState, or @{}. Returns @{ Ok; Problems; Lines;
|        Count (principals read back) }. A missing consent is a line, never a problem (the customer gives it).
|    #>
|    param([object[]]$Expect = @(), [hashtable]$Users = @{}, $Signin = $null, $Procedure = $null, [hashtable]$SupportGrant = @{})
|    $problems = New-Object System.Collections.Generic.List[string]; $lines = New-Object System.Collections.Generic.List[string]
|    $n = 0
|    foreach ($e in $Expect) {
|        $u = $null
|        if ($Users.ContainsKey($e.Database)) { $h = $Users[$e.Database]; $k = $e.ClientId.ToLowerInvariant(); if ($h -and $h.ContainsKey($k)) { $u = $h[$k] } }
|        if (-not $u) { $problems.Add(('{0}: the {1} identity {2} has no user (by its client id)' -f $e.Database, $e.Component, $e.Name)); continue }
|        $miss = @($e.Roles | Where-Object { -not $u.Roles.Contains($_) })
|        if ($miss.Count) { $problems.Add(('{0}: {1} ({2}) is not in {3}' -f $e.Database, $u.Name, $e.Component, ($miss -join ', '))); continue }
|        $n++
|        $lines.Add(('read back: {0}: {1} ({2}) in {3}' -f $e.Database, $u.Name, $e.Component, ($e.Roles -join ', ')))
|    }
|    if ($null -ne $Signin) {
|        if ($Signin.SchemaOk -and $Signin.CreateTable) { $lines.Add(('read back: the schema signin belongs to {0}, who may create tables' -f $Signin.User)) }
|        else { $problems.Add(('the sign-in front''s store is not complete (schema signin {0}, CREATE TABLE {1})' -f $(if ($Signin.SchemaOk) { 'ok' } else { 'not owned by the web identity' }), $(if ($Signin.CreateTable) { 'granted' } else { 'missing' }))) }
|    }
|    if ($null -ne $Procedure) {
|        if ($Procedure.Ok) { $lines.Add('read back: the signed grant procedure is in place and the updater may run it') }
|        else { foreach ($l in @($Procedure.Lines)) { $problems.Add(('the signed grant procedure: {0}' -f $l)) } }
|    }
|    foreach ($d in @($SupportGrant.Keys)) {
|        $st = $SupportGrant[$d]
|        foreach ($l in @($st.Lines)) { if ($l -match 'no consent is recorded') { $lines.Add(('{0}: {1} (the customer gives it)' -f $d, $l)) } else { $problems.Add(('{0}: the support grant: {1}' -f $d, $l)) } }
|        if ($st.Ok) { $lines.Add(('read back: {0}: the support grant is in place' -f $d)) }
|    }
|    [pscustomobject]@{ Ok = ($problems.Count -eq 0); Problems = $problems.ToArray(); Lines = $lines.ToArray(); Count = $n }
|}
|
|function New-SIDbInitRecordValue {
|    <# PURE. The result row's value: compact JSON, at most 400 characters (the column is NVARCHAR(400)); the reason is cut
|       first. -State ok | failed | waiting. #>
|    param([Parameter(Mandatory)][ValidateSet('ok', 'failed', 'waiting')][string]$State, [string]$Run = '', [string]$By = '', [int]$Count = 0,
|          [string]$Why = '', [datetime]$NowUtc = [datetime]::UtcNow)
|    $max = (Get-SIDbInitNames).RecordMax
|    $o = [ordered]@{ state = $State; at = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) }
|    if ($Run) { $o.run = $Run }
|    if ($By) { $o.by = $By }
|    $o.n = $Count
|    $w = [regex]::Replace([regex]::Replace("$Why", '[\x00-\x1F]', ' '), '\s+', ' ').Trim()
|    $o.why = ''
|    $base = (ConvertTo-Json -InputObject $o -Compress).Length
|    $room = $max - $base - 8
|    if ($w.Length -gt $room) { $w = $(if ($room -gt 3) { $w.Substring(0, $room - 3).TrimEnd() + '...' } else { '' }) }
|    $o.why = $w
|    $v = ConvertTo-Json -InputObject $o -Compress
|    # an escaped character can still push it over: cut the reason until it fits (it still ends with '...')
|    while ($v.Length -gt $max -and $w.Length -gt 0) {
|        $w = $w.Substring(0, [Math]::Max(0, $w.Length - 10))
|        $o.why = $(if ($w.Length -gt 3) { $w.Substring(0, $w.Length - 3).TrimEnd() + '...' } else { '' })
|        $v = ConvertTo-Json -InputObject $o -Compress
|    }
|    if (-not $o.why) { $o.Remove('why'); $v = ConvertTo-Json -InputObject $o -Compress }
|    $v
|}
|
|function ConvertFrom-SIDbInitRecordValue {
|    <# PURE. The result row's value as an object (@{ state; at; run; by; n; why }), or $null. #>
|    param([AllowNull()][AllowEmptyString()][string]$Value)
|    if (-not "$Value".Trim()) { return $null }
|    try { $o = "$Value" | ConvertFrom-Json -ErrorAction Stop } catch { return $null }
|    if (-not ($o -is [System.Management.Automation.PSCustomObject]) -or -not $o.PSObject.Properties['state']) { return $null }
|    $o
|}
|
|function Get-SIDbInitRecordSql {
|    <# PURE. The ONE write of the result: cfg.InstallState 'DbJob' (@Value, @Version, @By), written or replaced. -Name: another
|       row of the job's (the membership's own row, 'DbJobMembership'). #>
|    param([ValidatePattern('^[A-Za-z]{1,40}$')][string]$Name = '')
|    $n = if ($Name) { $Name } else { (Get-SIDbInitNames).Record }
|    @"
|IF OBJECT_ID(N'cfg.InstallState') IS NOT NULL
|BEGIN
|    IF EXISTS (SELECT 1 FROM cfg.InstallState WHERE Name = N'$n')
|        UPDATE cfg.InstallState SET Value = @Value, [Version] = @Version, UpdatedAt = SYSUTCDATETIME(), UpdatedBy = @By WHERE Name = N'$n';
|    ELSE INSERT cfg.InstallState (Name, Value, [Version], UpdatedBy) VALUES (N'$n', @Value, @Version, @By);
|END
|"@
|}
|
|function Get-SIDbInitRecordReadSql {
|    <# PURE. READ ONLY: the result row's value ('' = none, or no table). -Name: another row of the job's (#1146: the row of
|       one caller, Get-SIDbInitCallerRecordName). #>
|    param([ValidatePattern('^$|^[A-Za-z]{1,40}$')][string]$Name = '')
|    $n = if ($Name) { $Name } else { (Get-SIDbInitNames).Record }
|    "IF OBJECT_ID(N'cfg.InstallState') IS NOT NULL SELECT Value FROM cfg.InstallState WHERE Name = N'$n';"
|}
|
|function Test-SIDbInitLoginRefused {
|    <# PURE. Is this SQL error a refused sign-in (the membership is new or still replicating) -- waited for, never a stop? #>
|    param([AllowEmptyString()][string]$Message)
|    [bool]("$Message" -match '(?i)Login failed|18456|token-identified principal|not allowed to access|40615')
|}
|
|function Get-SIDbInitStandingOffNames {
|    <# PURE. #1151 SEC-01: the job's row of the standing-off result (cfg.InstallState), read by the updater. #>
|    @{ Record = 'DbJobSupportStanding' }
|}
|
|function Invoke-SIDbInitStandingOff {
|    <#
|        #1151 (1) SEC-01 / OPEN-01, THE JOB'S SIDE: in each of -Databases, Get-SISupportStandingOffSql (engine\pro-settings\
|        SI-SupportGrantSql.ps1) -- db_owner off the Support app's own user ONLY where the just-in-time path reads back in that
|        database, in the same batch. Nothing else is changed: no user dropped, no group, no server administrator. A database
|        that cannot be read or is not ready keeps what it has. Never throws. -Sql: the job's seam. Returns @{ State (off =
|        no product database holds the Support app's standing db_owner any more | kept = at least one still does | unknown =
|        the statement is not in this package); Databases (ordered db -> off | none | absent | kept); Why; Lines }.
|    #>
|    param([Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][scriptblock]$Sql, [string[]]$Databases = @())
|    $lines = New-Object System.Collections.Generic.List[string]
|    $per = [ordered]@{}; $why = New-Object System.Collections.Generic.List[string]
|    if (-not (Get-Command -Name Get-SISupportStandingOffSql -ErrorAction SilentlyContinue)) {
|        return [pscustomobject]@{ State = 'unknown'; Databases = $per; Why = 'this package cannot take the standing access off'; Lines = @('not in this package: the Support app''s standing db_owner off (support-standing-off)') }
|    }
|    foreach ($d in @($Databases | Where-Object { $_ } | Select-Object -Unique)) {
|        try {
|            $r = ConvertFrom-SISupportStandingOffRow -Row (@(& $Sql $d (Get-SISupportStandingOffSql -ClientId $ClientId) @{} 'rows' | ForEach-Object { $_ } | Where-Object { $null -ne $_ }) | Select-Object -First 1)
|        } catch { $r = [pscustomobject]@{ State = 'kept'; Roles = @(); Why = ('could not be read ({0})' -f $_.Exception.Message) } }
|        $per[$d] = $r.State
|        switch ($r.State) {
|            'off'    { $lines.Add(('support standing access: {0}: db_owner taken off the Invardia Support app''s own user -- the just-in-time path read back first; read back after: {1}' -f $d, $(if (@($r.Roles).Count) { @($r.Roles) -join ', ' } else { '(no role)' }))) }
|            'none'   { $lines.Add(('support standing access: {0}: the Invardia Support app holds no standing db_owner here' -f $d)) }
|            'absent' { $lines.Add(('support standing access: {0}: the Invardia Support app has no user here' -f $d)) }
|            default  { $why.Add(('{0}: {1}' -f $d, $r.Why)); $lines.Add(('support standing access: {0}: db_owner KEPT, nothing changed -- {1}' -f $d, $r.Why)) }
|        }
|    }
|    $state = if (-not $per.Count) { 'unknown' } elseif (@($per.Values | Where-Object { $_ -eq 'kept' }).Count) { 'kept' } else { 'off' }
|    [pscustomobject]@{ State = $state; Databases = $per; Why = ($why.ToArray() -join '; '); Lines = $lines.ToArray() }
|}
|
|function New-SIDbInitStandingOffRecordValue {
|    <# PURE. The row DbJobSupportStanding: compact JSON { state, at, run, dbs: 'db:off;db2:none', why }, at most 400 characters
|       (the reason is cut first). #>
|    param([Parameter(Mandatory)][ValidateSet('off', 'kept', 'unknown')][string]$State, [string]$Run = '', [System.Collections.IDictionary]$Databases = @{},
|          [string]$Why = '', [datetime]$NowUtc = [datetime]::UtcNow)
|    $max = (Get-SIDbInitNames).RecordMax
|    $o = [ordered]@{ state = $State; at = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) }
|    if ($Run) { $o.run = $Run }
|    $o.dbs = ((@($Databases.Keys) | ForEach-Object { '{0}:{1}' -f $_, $Databases[$_] }) -join ';')
|    if ($o.dbs.Length -gt 200) { $o.dbs = $o.dbs.Substring(0, 197) + '...' }
|    $w = [regex]::Replace([regex]::Replace("$Why", '[\x00-\x1F]', ' '), '\s+', ' ').Trim()
|    $room = $max - (ConvertTo-Json -InputObject $o -Compress).Length - 16
|    if ($w.Length -gt $room) { $w = $(if ($room -gt 3) { $w.Substring(0, $room - 3).TrimEnd() + '...' } else { '' }) }
|    if ($w) { $o.why = $w }
|    $v = ConvertTo-Json -InputObject $o -Compress
|    while ($v.Length -gt $max -and $o.Contains('why') -and ([string]$o.why).Length -gt 16) { $o.why = ([string]$o.why).Substring(0, ([string]$o.why).Length - 13) + '...'; $v = ConvertTo-Json -InputObject $o -Compress }
|    $v
|}
|
|function Invoke-SIDbInit {
|    <#
|        THE JOB'S RUN. -DbInput: Read-SIDbInitInput. -Sql: the seam (see the file's help) -- each call gets a fresh token from
|        the caller. -Log { param($m) } prints a line. Returns @{ ExitCode (0 = every principal read back; 1 = a step or the
|        read-back failed; 2 = refused inputs); Verdict; Lines; Record }. A refused sign-in is waited for (-LoginTries x
|        -LoginWaitSeconds, a fresh token each time); a database that is not there (the ledger on an older install) is a line.
|    #>
|    param([Parameter(Mandatory)]$DbInput, [Parameter(Mandatory)][scriptblock]$Sql, [scriptblock]$Log = { param($m) Write-Host $m },
|          [string]$Version = '', [int]$LoginTries = 16, [int]$LoginWaitSeconds = 20, [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s },
|          [scriptblock]$Now = { [datetime]::UtcNow }, [int[]]$DeadlockWaits = (Get-SIDbInitNames).DeadlockWaits)
|    $out = New-Object System.Collections.Generic.List[string]
|    $say = { param($m) $out.Add([string]$m); $null = & $Log $m }
|    $res = { param($code, $verdict, $rec) [pscustomobject]@{ ExitCode = $code; Verdict = $verdict; Lines = $out.ToArray(); Record = $rec } }
|    if (-not $DbInput.Ok) { & $say ('refused: {0}' -f $DbInput.Reason); return (& $res 2 'refused' '') }
|    $pro = $DbInput.Database; $led = $DbInput.LedgerDatabase
|    & $say ('the database setup job: {0}/{1}{2}; identities {3}{4}' -f $DbInput.Server, $pro, $(if ($led) { ' + ' + $led } else { '' }),
|        ((@($DbInput.Principals | ForEach-Object { '{0}={1}' -f $_.Component, $_.Name })) -join ', '), $(if ($DbInput.Support) { '; the Invardia Support app ' + $DbInput.Support.UserName } else { '' }))
|    # 1. the sign-in: the job's identity is the admin only through the group
|    $ok = $false
|    for ($i = 1; $i -le $LoginTries; $i++) {
|        try { $null = & $Sql $pro 'SELECT 1' @{} 'rows'; $ok = $true; break }
|        catch {
|            $m = [string]$_.Exception.Message
|            if (-not (Test-SIDbInitLoginRefused -Message $m)) { & $say ('the database could not be reached: {0}' -f $m); return (& $res 1 'failed' '') }
|            & $say ('the sign-in was refused (try {0} of {1}) -- the identity''s membership of the SQL admin group may still be replicating: {2}' -f $i, $LoginTries, $m)
|            if ($i -lt $LoginTries) { & $Sleep $LoginWaitSeconds }
|        }
|    }
|    if (-not $ok) { & $say ('the job''s identity could not sign in to the database as a member of the SQL admin group after {0} tries -- is it a member of the group that is the server''s administrator?' -f $LoginTries); return (& $res 1 'failed' '') }
|    # #1146: ONE statement that changes something, sent again when SQL chose it as a DEADLOCK victim (1205: rolled back so
|    # another session could finish -- nothing of it stayed) after a short growing wait, said each time; any other error, or a
|    # deadlock after the last wait, is thrown as it was
|    $dlWaits = @($DeadlockWaits | Where-Object { $_ -ge 0 })
|    $send = {
|        param([string]$db, [string]$q, $p, [string]$what)
|        $try = 0
|        while ($true) {
|            try { $null = & $Sql $db $q $p 'nonquery'; return }
|            catch {
|                $m = [string]$_.Exception.Message
|                if (-not (Test-SIDbInitDeadlock -Message $m) -or $try -ge $dlWaits.Count) { throw }
|                $w = [int]$dlWaits[$try]; $try++
|                & $say ('{0}: chosen as a deadlock victim by SQL (1205: another session held the same rows; nothing of this statement stayed) -- sent again in {1} s (try {2} of {3})' -f $what, $w, ($try + 1), ($dlWaits.Count + 1))
|                & $Sleep $w
|            }
|        }
|    }
|    $writeRecord = {
|        param($state, $count, $why)
|        $v = New-SIDbInitRecordValue -State $state -Run $DbInput.Run -By $DbInput.By -Count $count -Why $why -NowUtc (& $Now)
|        $rp = @{ Value = $v; Version = $(if ($Version) { $Version.Substring(0, [Math]::Min(32, $Version.Length)) } else { $null }); By = (Get-SIDbInitNames).Job }
|        try { & $send $pro (Get-SIDbInitRecordSql) $rp 'the result row'; & $say ('result recorded: {0}' -f $v) }
|        catch { & $say ('WARNING: the result could not be recorded: {0}' -f $_.Exception.Message) }
|        # #1146: the same result in the row of THIS caller (DbJobUpdater / DbJobSupport / DbJobInstaller): a run started beside
|        # another one never overwrites the result the other caller waits for
|        $own = Get-SIDbInitCallerRecordName -By $DbInput.By
|        try { & $send $pro (Get-SIDbInitRecordSql -Name $own) $rp ('the result row ' + $own) }
|        catch { & $say ('WARNING: the result could not be recorded in {0}: {1}' -f $own, $_.Exception.Message) }
|        $v
|    }
|    $usersOf = { param($d) ConvertFrom-SIDbInitUsers -Rows @(& $Sql $d (Get-SIDbInitUsersSql) @{} 'rows' | ForEach-Object { $_ }) }
|    try {
|        # 2. what is there BEFORE: the users (a user under another name is used by that name), the procedure, the consent
|        $ledOk = $false
|        if ($led) {
|            try { $null = & $Sql $led 'SELECT 1' @{} 'rows'; $ledOk = $true }
|            catch { & $say ('the identity ledger {0} could not be opened ({1}) -- its steps are left out' -f $led, $_.Exception.Message) }
|        }
|        $in = $DbInput
|        if (-not $ledOk -and $led) { $in = $DbInput.PSObject.Copy(); $in.LedgerDatabase = '' }
|        $users = & $usersOf $pro
|        $ledUsers = if ($in.LedgerDatabase) { & $usersOf $in.LedgerDatabase } else { @{} }
|        $procInstalled = $false
|        if (Get-Command -Name Get-SIGrantProcedureStateSql -ErrorAction SilentlyContinue) {
|            $st = ConvertFrom-SIGrantProcedureState -Row (@(& $Sql $pro (Get-SIGrantProcedureStateSql) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1)
|            $procInstalled = [bool]$st.Installed
|        }
|        $consent = ''
|        if ($in.Support -and (Get-Command -Name Get-SISupportGrantConsentReadSql -ErrorAction SilentlyContinue)) {
|            $row = @(& $Sql $pro (Get-SISupportGrantConsentReadSql) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1
|            $consent = ([string](Get-SIDbInitProp $row @('Consent'))).Trim()
|        }
|        # #1021: the OTHER product databases (the server is SecurityInsight's own: its user databases, read in master; the
|        # ledger as given) and the Pro database's consent row -- what the support grant needs in each of them
|        $others = New-Object System.Collections.Generic.List[string]
|        if ($in.LedgerDatabase) { $others.Add($in.LedgerDatabase) }
|        try {
|            foreach ($r in @(& $Sql 'master' (Get-SIDbInitDatabasesSql) @{} 'rows' | ForEach-Object { $_ })) {
|                $dn = [string](Get-SIDbInitProp $r @('Name'))
|                if ($dn -and $dn -ne $pro -and $dn -match '^[A-Za-z0-9_.-]{1,128}$' -and -not $others.Contains($dn)) { $others.Add($dn) }
|            }
|        } catch { & $say ('the server''s other databases could not be listed ({0}) -- only the identity ledger is checked for the support grant' -f $_.Exception.Message) }
|        $proConsent = $null
|        try { $proConsent = @(& $Sql $pro (Get-SIDbInitConsentReadSql) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1 } catch { $proConsent = $null }
|        # 3. the batches, in order
|        $plan = Get-SIDbInitPlan -DbInput $in -Users $users -LedgerUsers $ledUsers -ProcedureInstalled $procInstalled -Consent $consent -SupportDatabases $others.ToArray() -ProConsent $proConsent
|        foreach ($s in $plan.Skipped) { & $say ('not in this package: {0}' -f $s) }
|        $planned = @{}
|        foreach ($bt in $plan.Batches) {
|            try { & $send $bt.Database $bt.Sql $bt.Params $bt.Name; & $say ('done: {0}' -f $bt.Name); $planned[$bt.Step] = $true }
|            catch {
|                if (-not $bt.Required) { & $say ('WARNING: {0}: {1}' -f $bt.Name, $_.Exception.Message); continue }
|                throw ('{0}: {1}' -f $bt.Name, $_.Exception.Message)
|            }
|        }
|        # 3b. THE IDENTITY MOVE (only when this execution names moves / drops): copy and read back, then drop only what the
|        # kept identity reads back holding -- in the Pro database, the identity ledger and every other product database
|        $mvRes = $null
|        if (@($in.Moves).Count -or @($in.Drops).Count) {
|            $mvDbs = @(@($pro) + @($others.ToArray()) | Where-Object { $_ } | Select-Object -Unique)
|            $mvRes = Invoke-SIDbInitMoves -DbInput $in -Sql $Sql -Databases $mvDbs
|            foreach ($l in $mvRes.Lines) { & $say $l }
|            $mvVal = New-SIDbInitMovesRecordValue -Run $in.Run -States $mvRes.States -NowUtc (& $Now)
|            try { $null = & $Sql $pro (Get-SIDbInitRecordSql -Name 'DbJobMoves') @{ Value = $mvVal; Version = $null; By = (Get-SIDbInitNames).Job } 'nonquery'; & $say ('identity move recorded: {0}' -f $mvVal) }
|            catch { & $say ('WARNING: the identity move''s result could not be recorded: {0}' -f $_.Exception.Message) }
|        }
|        # 3c. #1151 SEC-01: the Support app's STANDING db_owner taken off (only when the updater names it, only where the
|        # just-in-time path reads back in the same batch) -- never part of the verdict: a database that is not ready keeps it
|        if ([string](Get-SIDbInitProp $in @('StandingOff'))) {
|            $soDbs = @(@($pro) + @($others.ToArray()) | Where-Object { $_ } | Select-Object -Unique)
|            $so = Invoke-SIDbInitStandingOff -ClientId ([string]$in.StandingOff) -Sql $Sql -Databases $soDbs
|            foreach ($l in $so.Lines) { & $say $l }
|            $soVal = New-SIDbInitStandingOffRecordValue -Run $in.Run -State $so.State -Databases $so.Databases -Why $so.Why -NowUtc (& $Now)
|            try { $null = & $Sql $pro (Get-SIDbInitRecordSql -Name (Get-SIDbInitStandingOffNames).Record) @{ Value = $soVal; Version = $null; By = (Get-SIDbInitNames).Job } 'nonquery'; & $say ('support standing access recorded: {0}' -f $soVal) }
|            catch { & $say ('WARNING: the support standing access result could not be recorded: {0}' -f $_.Exception.Message) }
|        }
|        # 4. THE READ-BACK (read only)
|        $after = @{}; $after[$pro] = & $usersOf $pro
|        if ($in.LedgerDatabase) { $after[$in.LedgerDatabase] = & $usersOf $in.LedgerDatabase }
|        $signin = $null
|        $web = @($in.Principals | Where-Object { $_.Component -eq 'web' })[0]
|        if ($web -and $planned.ContainsKey('signin-schema') -and (Get-Command -Name Get-SISigninStoreStateSql -ErrorAction SilentlyContinue)) {
|            $signin = ConvertFrom-SISigninStoreStateRow -Row (@(& $Sql $pro (Get-SISigninStoreStateSql) @{ ClientId = $web.ClientId; UserName = $web.Name } 'rows' | ForEach-Object { $_ }) | Select-Object -First 1)
|        }
|        $proc = $null
|        if ($plan.Procedure) {
|            $upd = @($in.Principals | Where-Object { $_.Component -eq 'updater' })[0]
|            $un = if ($after[$pro].ContainsKey($upd.ClientId.ToLowerInvariant())) { $after[$pro][$upd.ClientId.ToLowerInvariant()].Name } else { $upd.Name }
|            $proc = Test-SIGrantProcedureReady -State (ConvertFrom-SIGrantProcedureState -Row (@(& $Sql $pro (Get-SIGrantProcedureStateSql -UpdaterUser $un) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1)) -RequireUpdaterMember
|        }
|        $sg = @{}
|        if ($in.Support -and $planned.ContainsKey('support-grant-schema') -and (Get-Command -Name Get-SISupportGrantStateSql -ErrorAction SilentlyContinue)) {
|            foreach ($d in @($pro) + @($(if ($in.LedgerDatabase) { $in.LedgerDatabase }))) {
|                $sg[$d] = ConvertFrom-SISupportGrantState -Row (@(& $Sql $d (Get-SISupportGrantStateSql -ClientId $in.Support.ClientId) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1)
|            }
|        }
|        $expect = @(Get-SIDbInitExpectations -DbInput $in -Procedure ([bool]$plan.Procedure) -PlannedSteps $planned)
|        $t = Test-SIDbInitReadBack -Expect $expect -Users $after -Signin $signin -Procedure $proc -SupportGrant $sg
|        # #1021: each other product database, read back (only where the support grant is); the list recorded for the updater
|        $engP = @($in.Principals | Where-Object { $_.Component -eq 'engine' })[0]; $updP = @($in.Principals | Where-Object { $_.Component -eq 'updater' })[0]
|        $sgDbs = New-Object System.Collections.Generic.List[string]
|        $more = New-Object System.Collections.Generic.List[string]
|        foreach ($d in $others) {
|            try {
|                $st = Test-SIDbInitSupportDbState -Row (@(& $Sql $d (Get-SIDbInitSupportDbStateSql -EngineClientId $engP.ClientId -UpdaterClientId $(if ($updP) { $updP.ClientId } else { '' })) @{} 'rows' | ForEach-Object { $_ }) | Select-Object -First 1) -Updater ([bool]$updP)
|                if (-not $st.Applies) { continue }
|                $sgDbs.Add($d)
|                if ($st.Problems.Count) { foreach ($x in $st.Problems) { $more.Add(('{0}: {1}' -f $d, $x)) } } else { & $say ('read back: {0}: the engine may run the support grant procedures; the updater may mirror the consent' -f $d) }
|            } catch { $more.Add(('{0}: the support grant''s rights could not be read back ({1})' -f $d, $_.Exception.Message)) }
|        }
|        if ($mvRes -and @($mvRes.Problems).Count) { foreach ($x in $mvRes.Problems) { $more.Add(('identity move: {0}' -f $x)) } }
|        if ($more.Count) { $t = [pscustomobject]@{ Ok = $false; Problems = @($t.Problems) + $more.ToArray(); Lines = $t.Lines; Count = $t.Count } }
|        try { $null = & $Sql $pro (Get-SIDbInitDatabasesRecordSql) @{ Value = ($sgDbs.ToArray() -join ';') } 'nonquery' } catch { & $say ('WARNING: the list of the other product databases could not be recorded: {0}' -f $_.Exception.Message) }
|        foreach ($l in $t.Lines) { & $say $l }
|        foreach ($p in $t.Problems) { & $say ('NOT OK: {0}' -f $p) }
|        if (-not $t.Ok) {
|            $rec = & $writeRecord 'failed' $t.Count (($t.Problems | Select-Object -First 2) -join '; ')
|            & $say 'verdict: FAILED -- see the lines above'
|            return (& $res 1 'failed' $rec)
|        }
|        $rec = & $writeRecord 'ok' $t.Count ''
|        & $say ('verdict: every identity read back ({0})' -f $t.Count)
|        return (& $res 0 'ok' $rec)
|    } catch {
|        $why = [string]$_.Exception.Message
|        & $say ('failed: {0}' -f $why)
|        $rec = & $writeRecord 'failed' 0 $why
|        return (& $res 1 'failed' $rec)
|    }
|}
|
|# =====================================================================================================================
|#  THE CALLERS' SIDE (the guided install, the updater, the support repair): the identity, the membership, the job, a run
|# =====================================================================================================================
|
|function Get-SIDbInitTemplateJob {
|    <# PURE. The engine job whose environment, image and pull identity the database job takes: a job of the install that is
|       not the updater, asset tagging, a one-time support job or this job itself, and that pulls its image with a
|       user-assigned identity. Returns @{ Ok; Problem; Name; EnvironmentId; Location; Image; RegistryServer; PullIdentityId }. #>
|    param([object[]]$Jobs = @())
|    $n = Get-SIDbInitNames
|    $cand = @($Jobs | Where-Object { $_ -and [string](Get-SIDbInitProp $_ @('name')) -notmatch '(?i)updater|tagging|supportsql|supportread|support-grant|dbinit|index-build' -and -not [string](Get-SIDbInitProp $_ @('tags', 'si-one-time-job')) -and [string](Get-SIDbInitProp $_ @('tags', $n.TagName)) -ne $n.TagValue })
|    foreach ($j in $cand) {
|        $c0 = @(Get-SIDbInitProp $j @('properties', 'template', 'containers'))[0]
|        $img = [string](Get-SIDbInitProp $c0 @('image'))
|        $reg = @(Get-SIDbInitProp $j @('properties', 'configuration', 'registries') | Where-Object { $_ })[0]
|        $pull = [string](Get-SIDbInitProp $reg @('identity'))
|        if (-not $img -or $img -notmatch '/si-orchestrator[:@]') { continue }
|        if ($pull -notmatch '(?i)/providers/Microsoft\.ManagedIdentity/userAssignedIdentities/') { continue }
|        # the install's SI workspace, as the engine job names it (where the environment's console lines must go)
|        $ws = @(@(Get-SIDbInitProp $c0 @('env')) | Where-Object { $_ -and [string](Get-SIDbInitProp $_ @('name')) -ieq 'SI_WorkspaceResourceId' } | ForEach-Object { ([string](Get-SIDbInitProp $_ @('value'))).Trim() } | Where-Object { $_ })[0]
|        return [pscustomobject]@{ Ok = $true; Problem = ''; Name = [string](Get-SIDbInitProp $j @('name')); EnvironmentId = [string](Get-SIDbInitProp $j @('properties', 'environmentId'))
|                                  Location = [string](Get-SIDbInitProp $j @('location')); Image = $img; RegistryServer = [string](Get-SIDbInitProp $reg @('server')); PullIdentityId = $pull
|                                  WorkspaceResourceId = [string]$ws }
|    }
|    [pscustomobject]@{ Ok = $false; Problem = 'no engine job runs the SecurityInsight image with a managed identity for its registry -- the database job takes its image and environment from one' }
|}
|
|function Get-SIDbInitPrincipals {
|    <#
|        PURE. The product identities from the install's own Azure resources: -Identities (the resource group's user-assigned
|        identities, ARM shape), -Jobs and -Apps (ARM shape). Engine = the identity whose client id the engine jobs carry
|        (SI_UAMI_ClientId); web / MCP = the identity of the container app named -WebApp / -McpApp; updater = the identity of
|        the job -UpdaterJob; asset tagging = the identity named -TaggingIdentity. One that is not there is left out.
|        Returns the list for SI_DBINIT_PRINCIPALS (@{ component; name; clientId }).
|    #>
|    param([object[]]$Identities = @(), [object[]]$Jobs = @(), [object[]]$Apps = @(), [string[]]$WebApp = @('ca-si-management', 'ca-si-web'), [string[]]$McpApp = @('ca-si-mcp'),
|          [string[]]$UpdaterJob = @('caj-si-updater'), [string[]]$TaggingIdentity = @('uami-securityinsight-tagging', 'id-si-tagging'), [string]$EngineClientId = '')
|    $out = New-Object System.Collections.Generic.List[object]
|    $byId = @{}; $byCid = @{}; $byName = @{}
|    foreach ($m in @($Identities | Where-Object { $_ })) {
|        $o = [pscustomobject]@{ Name = [string](Get-SIDbInitProp $m @('name')); ClientId = [string](Get-SIDbInitProp $m @('properties', 'clientId')); Id = ([string](Get-SIDbInitProp $m @('id'))).ToLowerInvariant() }
|        if (-not $o.ClientId) { continue }
|        $byId[$o.Id] = $o; $byCid[$o.ClientId.ToLowerInvariant()] = $o; $byName[$o.Name.ToLowerInvariant()] = $o
|    }
|    # The identity an app / job SIGNS IN AS: the attached identity whose client id its own containers' settings name
|    # (Identity__ManagedIdentityClientId, AZURE_CLIENT_ID, SI_UPDATER_CLIENT_ID, ...). During an identity move the old
|    # and the new identity are both attached until the clean-up -- the first attached one was the OLD one (live at the
|    # internal install 2026-11-05). Only when no setting names one: the first attached identity, as before.
|    $firstUa = { param($r) $ua = Get-SIDbInitProp $r @('identity', 'userAssignedIdentities'); if (-not $ua) { return $null }
|        $keys = if ($ua -is [System.Collections.IDictionary]) { @($ua.Keys) } else { @($ua.PSObject.Properties | ForEach-Object { $_.Name }) }
|        $att = @(foreach ($k in $keys) { $kk = ([string]$k).ToLowerInvariant(); if ($byId.ContainsKey($kk)) { $byId[$kk] } })
|        foreach ($c in @(Get-SIDbInitProp $r @('properties', 'template', 'containers'))) {
|            foreach ($e in @(Get-SIDbInitProp $c @('env'))) {
|                $v = ([string](Get-SIDbInitProp $e @('value'))).Trim().ToLowerInvariant()
|                if ($v -match '^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$') { $hit = @($att | Where-Object { $_.ClientId.ToLowerInvariant() -eq $v })[0]; if ($hit) { return $hit } }
|            }
|        }
|        @($att)[0] }
|    $put = { param($c, $o) if ($o -and $o.ClientId -and -not @($out | Where-Object { $_.component -eq $c -or $_.clientId -eq $o.ClientId }).Count) { $out.Add([ordered]@{ component = $c; name = $o.Name; clientId = $o.ClientId }) } }
|    $ecid = "$EngineClientId".Trim()
|    if (-not $ecid) {
|        foreach ($j in @($Jobs | Where-Object { $_ -and [string](Get-SIDbInitProp $_ @('name')) -notmatch '(?i)updater|tagging|dbinit' })) {
|            foreach ($c in @(Get-SIDbInitProp $j @('properties', 'template', 'containers'))) {
|                foreach ($e in @(Get-SIDbInitProp $c @('env'))) { if ([string](Get-SIDbInitProp $e @('name')) -eq 'SI_UAMI_ClientId') { $v = ([string](Get-SIDbInitProp $e @('value'))).Trim(); if ($v) { $ecid = $v; break } } }
|                if ($ecid) { break }
|            }
|            if ($ecid) { break }
|        }
|    }
|    if ($ecid -and $byCid.ContainsKey($ecid.ToLowerInvariant())) { & $put 'engine' $byCid[$ecid.ToLowerInvariant()] }
|    $named = { param($list, $names) $l = @($names | Where-Object { $_ } | ForEach-Object { ([string]$_).ToLowerInvariant() }); @($list | Where-Object { $_ -and $l -contains ([string](Get-SIDbInitProp $_ @('name'))).ToLowerInvariant() })[0] }
|    $u = & $named $Jobs $UpdaterJob; if ($u) { & $put 'updater' (& $firstUa $u) }
|    $w = & $named $Apps $WebApp; if ($w) { & $put 'web' (& $firstUa $w) }
|    $m2 = & $named $Apps $McpApp; if ($m2) { & $put 'mcp' (& $firstUa $m2) }
|    foreach ($tn in @($TaggingIdentity | Where-Object { $_ })) { if ($byName.ContainsKey(([string]$tn).ToLowerInvariant())) { & $put 'tagging' $byName[([string]$tn).ToLowerInvariant()]; break } }
|    $out.ToArray()
|}
|
|function Get-SIDbInitJobBody {
|    <# PURE. caj-si-dbinit: manual trigger, one replica, no retry, 30 minutes, the engine image with the job's own entry
|       point, its OWN identity (+ the pull identity of the engine jobs, for the image only), tagged; no secret. The
|       execution-only inputs (the run id, who started it, the Support app) are given per start, never stored here. #>
|    param([Parameter(Mandatory)][string]$Location, [Parameter(Mandatory)][string]$EnvironmentId, [Parameter(Mandatory)][string]$Image,
|          [Parameter(Mandatory)][string]$RegistryServer, [Parameter(Mandatory)][string]$PullIdentityId, [Parameter(Mandatory)][string]$IdentityId,
|          [Parameter(Mandatory)][string]$IdentityClientId, [Parameter(Mandatory)][string]$Server, [string]$Database = 'sqldb-si-pro',
|          [string]$LedgerDatabase = 'sqldb-si-identity', [object[]]$Principals = @(), [bool]$SignedGrants = $false, [bool]$EngineRoleOnly = $false)
|    $n = Get-SIDbInitNames
|    $ua = [ordered]@{}; $ua[$IdentityId] = [ordered]@{}
|    if ($PullIdentityId.ToLowerInvariant() -ne $IdentityId.ToLowerInvariant()) { $ua[$PullIdentityId] = [ordered]@{} }
|    $tags = [ordered]@{ product = 'securityinsight' }; $tags[$n.TagName] = $n.TagValue
|    $env = @(
|        [ordered]@{ name = 'SI_DBINIT_SERVER'; value = $Server }
|        [ordered]@{ name = 'SI_DBINIT_DATABASE'; value = $Database }
|        [ordered]@{ name = 'SI_DBINIT_LEDGER_DATABASE'; value = $LedgerDatabase }
|        [ordered]@{ name = 'SI_DBINIT_MI_CLIENT_ID'; value = $IdentityClientId }
|        [ordered]@{ name = 'SI_DBINIT_PRINCIPALS'; value = (ConvertTo-Json -InputObject @($Principals) -Compress -Depth 5) }
|        [ordered]@{ name = 'SI_DBINIT_SIGNED_GRANTS'; value = $(if ($SignedGrants) { '1' } else { '0' }) }
|        [ordered]@{ name = 'SI_DBINIT_ENGINE_ROLE_ONLY'; value = $(if ($EngineRoleOnly) { '1' } else { '0' }) }
|    )
|    [ordered]@{
|        location = $Location; tags = $tags
|        identity = [ordered]@{ type = 'UserAssigned'; userAssignedIdentities = $ua }
|        properties = [ordered]@{
|            environmentId = $EnvironmentId
|            configuration = [ordered]@{
|                triggerType = 'Manual'; replicaTimeout = 1800; replicaRetryLimit = 0
|                manualTriggerConfig = [ordered]@{ parallelism = 1; replicaCompletionCount = 1 }
|                registries = @([ordered]@{ server = $RegistryServer; identity = $PullIdentityId })
|            }
|            template = [ordered]@{ containers = @([ordered]@{
|                name = $n.Container; image = $Image; command = @('pwsh', '-NoProfile', '-NonInteractive', '-File', $n.Entry)
|                resources = [ordered]@{ cpu = 0.5; memory = '1Gi' }; env = $env }) }
|        }
|    }
|}
|
|function Get-SIDbInitLogSettingBody {
|    <# PURE. The environment's diagnostic setting si-environment-logs: console + system lines to the install's SI workspace
|       (the same setting the container setup makes, #220 -- written out here so the job's callers need no other file). #>
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId)
|    [ordered]@{ properties = [ordered]@{ workspaceId = $WorkspaceResourceId; logs = @(
|        [ordered]@{ category = 'ContainerAppConsoleLogs'; enabled = $true },
|        [ordered]@{ category = 'ContainerAppSystemLogs'; enabled = $true }) } }
|}
|
|function Test-SIDbInitEnvironmentLogs {
|    <#
|        PURE. Do the console lines of a job in -Environment (ARM shape) reach a Log Analytics workspace? 'log-analytics' =
|        written there directly (its workspace named); 'azure-monitor' = only through a diagnostic setting of the environment
|        (-Settings, ARM shape) that sends ContainerAppConsoleLogs (or allLogs) to a workspace. Any other destination (none,
|        or not set) = the lines are in the portal's console view only. Returns @{ Ok; Destination; How }.
|    #>
|    param($Environment, [object[]]$Settings = @())
|    $dest = [string](Get-SIDbInitProp $Environment @('properties', 'appLogsConfiguration', 'destination'))
|    if ($dest -eq 'log-analytics') {
|        $cid = [string](Get-SIDbInitProp $Environment @('properties', 'appLogsConfiguration', 'logAnalyticsConfiguration', 'customerId'))
|        if ($cid) { return [pscustomobject]@{ Ok = $true; Destination = $dest; How = ('written directly to Log Analytics workspace {0}' -f $cid) } }
|        return [pscustomobject]@{ Ok = $false; Destination = $dest; How = 'the environment names Log Analytics but no workspace' }
|    }
|    if ($dest -eq 'azure-monitor') {
|        foreach ($s in @($Settings | Where-Object { $_ })) {
|            $ws = [string](Get-SIDbInitProp $s @('properties', 'workspaceId'))
|            if (-not $ws) { continue }
|            $on = @(@(Get-SIDbInitProp $s @('properties', 'logs')) | Where-Object { $_ -and [string](Get-SIDbInitProp $_ @('enabled')) -match '^(?i)true$' -and
|                    ([string](Get-SIDbInitProp $_ @('category')) -eq 'ContainerAppConsoleLogs' -or [string](Get-SIDbInitProp $_ @('categoryGroup')) -eq 'allLogs') })
|            if ($on.Count) { return [pscustomobject]@{ Ok = $true; Destination = $dest; How = ('through the diagnostic setting {0} to {1}' -f [string](Get-SIDbInitProp $s @('name')), ($ws -split '/')[-1]) } }
|        }
|        return [pscustomobject]@{ Ok = $false; Destination = $dest; How = 'the environment sends its logs through Azure Monitor, but no diagnostic setting sends its console lines to a workspace' }
|    }
|    [pscustomobject]@{ Ok = $false; Destination = $dest; How = ('the environment sends its logs nowhere (destination {0})' -f $(if ($dest) { $dest } else { 'not set' })) }
|}
|
|function Set-SIDbInitEnvironmentLogs {
|    <#
|        The job's lines reach Log Analytics at EVERY install (found live 2026-11-05: a run wrote nothing to the workspace, so
|        its failing line could not be read). Reads the environment the job runs in (-EnvironmentId: the engine jobs' one)
|        and its diagnostic settings; an environment that logs through Azure Monitor without a setting for its console lines
|        gets si-environment-logs to -WorkspaceResourceId (the install's SI workspace, as the engine jobs name it), READ BACK.
|        Never throws and never stops the job (a warning only: the run's lines then stay in the portal's console view).
|        Returns @{ Ok; Changed; Line }.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [string]$EnvironmentId, [string]$WorkspaceResourceId)
|    $api = '2021-05-01-preview'
|    $res = { param($ok, $ch, $l) [pscustomobject]@{ Ok = [bool]$ok; Changed = [bool]$ch; Line = [string]$l } }
|    if (-not "$EnvironmentId".Trim()) { return (& $res $false $false 'WARNING: the job''s environment is not known, so where its lines go was not checked') }
|    $envName = ($EnvironmentId.TrimEnd('/') -split '/')[-1]
|    try {
|        $envObj = & $Arm 'GET' ('{0}?api-version={1}' -f $EnvironmentId.TrimEnd('/'), (Get-SIDbInitNames).AppApi) $null
|        $readSettings = { @(Get-SIDbInitProp (& $Arm 'GET' ('{0}/providers/Microsoft.Insights/diagnosticSettings?api-version={1}' -f $EnvironmentId.TrimEnd('/'), $api) $null) @('value') | Where-Object { $_ }) }
|        $set = if ([string](Get-SIDbInitProp $envObj @('properties', 'appLogsConfiguration', 'destination')) -eq 'azure-monitor') { & $readSettings } else { @() }
|        $t = Test-SIDbInitEnvironmentLogs -Environment $envObj -Settings $set
|        if ($t.Ok) { return (& $res $true $false ('the job''s lines reach Log Analytics: the environment {0} -- {1}' -f $envName, $t.How)) }
|        if ($t.Destination -ne 'azure-monitor') { return (& $res $false $false ('WARNING: the job''s lines do not reach Log Analytics: {0} ({1}) -- they are in the portal''s console view of each run only' -f $t.How, $envName)) }
|        if (-not "$WorkspaceResourceId".Trim()) { return (& $res $false $false ('WARNING: the job''s lines do not reach Log Analytics: {0} ({1}), and the engine jobs name no SI workspace to send them to' -f $t.How, $envName)) }
|        $null = & $Arm 'PUT' ('{0}/providers/Microsoft.Insights/diagnosticSettings/si-environment-logs?api-version={1}' -f $EnvironmentId.TrimEnd('/'), $api) (Get-SIDbInitLogSettingBody -WorkspaceResourceId $WorkspaceResourceId.Trim())
|        $t2 = Test-SIDbInitEnvironmentLogs -Environment $envObj -Settings (& $readSettings)
|        if ($t2.Ok) { return (& $res $true $true ('the job''s lines now reach Log Analytics: the environment {0} -- {1} (made, read back)' -f $envName, $t2.How)) }
|        & $res $false $true ('WARNING: the diagnostic setting si-environment-logs was sent for the environment {0}, but reading it back did not show the console lines going to a workspace' -f $envName)
|    } catch {
|        & $res $false $false ('WARNING: where the job''s lines go could not be checked or set ({0}) -- they are in the portal''s console view of each run' -f $_.Exception.Message)
|    }
|}
|
|function Get-SIDbInitStartBody {
|    <# PURE. The body of ONE start: the job's own container (name, image, command, resources) and ITS environment with -Env
|       added or replacing a variable of the same name (an execution template REPLACES the environment, so everything is
|       carried). #>
|    param([Parameter(Mandatory)]$Job, [System.Collections.IDictionary]$Env = @{})
|    $c = @(Get-SIDbInitProp $Job @('properties', 'template', 'containers'))[0]
|    $vars = New-Object System.Collections.Generic.List[object]
|    foreach ($e in @(Get-SIDbInitProp $c @('env'))) {
|        if (-not $e) { continue }
|        $nm = [string](Get-SIDbInitProp $e @('name'))
|        if (-not $nm -or $Env.Contains($nm)) { continue }
|        $vars.Add([ordered]@{ name = $nm; value = [string](Get-SIDbInitProp $e @('value')) })
|    }
|    foreach ($k in $Env.Keys) { $vars.Add([ordered]@{ name = [string]$k; value = [string]$Env[$k] }) }
|    $o = [ordered]@{ name = [string](Get-SIDbInitProp $c @('name')); image = [string](Get-SIDbInitProp $c @('image')); env = $vars.ToArray() }
|    $cmd = @(Get-SIDbInitProp $c @('command') | Where-Object { $null -ne $_ }); if ($cmd.Count) { $o.command = $cmd }
|    $r = Get-SIDbInitProp $c @('resources')
|    if ($r) { $o.resources = [ordered]@{ cpu = [double](Get-SIDbInitProp $r @('cpu')); memory = [string](Get-SIDbInitProp $r @('memory')) } }
|    [ordered]@{ containers = @($o) }
|}
|
|function Test-SIDbInitMember {
|    <# Is the identity's service principal (-PrincipalId) a member of -GroupId? Read from the IDENTITY's side (its memberOf):
|       a group's /members list leaves service principals out for a caller without directory read rights (EPS 2.0.59, live at
|       an install 2026-11-04). THROWS when the directory cannot be asked. #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId)
|    $next = 'https://graph.microsoft.com/v1.0/servicePrincipals/{0}/memberOf?$select=id' -f $PrincipalId
|    for ($i = 0; $next -and $i -lt 20; $i++) {
|        $page = & $Graph 'GET' $next $null
|        foreach ($v in @(Get-SIDbInitProp $page @('value'))) { if ($v -and ([string](Get-SIDbInitProp $v @('id'))) -ieq $GroupId) { return $true } }
|        $next = [string](Get-SIDbInitProp $page @('@odata.nextLink'))
|    }
|    $false
|}
|
|function Add-SIDbInitMember {
|    <# The job's identity into the SQL admin group, READ BACK from the identity's side before anything starts the job (spec
|       point 7). Idempotent. Returns @{ State = already | added | refused | unchecked | notfound; Detail }. Needs
|       setup\_shared\SI-GroupMemberAdd.ps1 (the one add-and-wait policy). #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId,
|          [scriptblock]$Sleep, [scriptblock]$Print, [int]$LimitSeconds = 300, [datetime]$NowUtc = [datetime]::UtcNow)
|    try { if (Test-SIDbInitMember -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId) { return [pscustomobject]@{ State = 'already'; Detail = ('{0} is a member of the SQL admin group (read from its memberOf)' -f (Get-SIDbInitNames).Identity) } } } catch { }
|    $siDbGraph = $Graph; $siDbPid = $PrincipalId; $siDbGid = $GroupId
|    $r = Invoke-SIGroupMemberAddRetry -What ((Get-SIDbInitNames).Identity) -Sleep $Sleep -Print $Print -LimitSeconds $LimitSeconds `
|            -Add { $null = & $siDbGraph 'POST' ('https://graph.microsoft.com/v1.0/groups/{0}/members/$ref' -f $siDbGid) @{ '@odata.id' = ('https://graph.microsoft.com/v1.0/directoryObjects/{0}' -f $siDbPid) } } `
|            -Test { Test-SIDbInitMember -Graph $siDbGraph -PrincipalId $siDbPid -GroupId $siDbGid }
|    if ([string]$r.State -ne 'refused') { return [pscustomobject]@{ State = [string]$r.State; Detail = [string]$r.Detail } }
|    # 2026-11-05 (owner: "why is this not in setup"): a direct add refused (the caller may not change the group's members) --
|    # an ACTIVE PIM-for-Groups member assignment instead, the route the framework already accepts as membership. Permanent
|    # when the group's PIM policy allows it, else the longest the policy gives (180 days; said, so the renewal is known).
|    $pim = Add-SIDbInitPimMember -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -Sleep $Sleep -Print $Print -LimitSeconds $LimitSeconds -NowUtc $NowUtc
|    if ($pim.State -eq 'added') { return $pim }
|    [pscustomobject]@{ State = 'refused'; Detail = ('{0}; the PIM-for-Groups assignment was refused too: {1}' -f [string]$r.Detail, [string]$pim.Detail) }
|}
|
|function Get-SIDbInitPimMemberBody {
|    <# PURE. The ACTIVE PIM-for-Groups member assignment of -PrincipalId to -GroupId. -Days 0 = permanent (noExpiration).
|       -Action: adminAssign (a new one), adminExtend (an active one that ends soon), adminUpdate (its schedule changed),
|       adminRenew (one that has ended) -- Microsoft Graph's privilegedAccessGroupAssignmentScheduleRequest actions. #>
|    param([Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId, [int]$Days = 0, [datetime]$Now = [datetime]::UtcNow,
|          [ValidateSet('adminAssign', 'adminExtend', 'adminUpdate', 'adminRenew')][string]$Action = 'adminAssign')
|    $exp = if ($Days -gt 0) { [ordered]@{ type = 'afterDuration'; duration = ('P{0}D' -f $Days) } } else { [ordered]@{ type = 'noExpiration' } }
|    [ordered]@{
|        accessId      = 'member'
|        principalId   = $PrincipalId
|        groupId       = $GroupId
|        action        = $Action
|        justification = 'SecurityInsight database setup job: member of the SQL server''s admin group (no person needs database admin rights)'
|        scheduleInfo  = [ordered]@{ startDateTime = $Now.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture); expiration = $exp }
|    }
|}
|
|function ConvertFrom-SIDbInitIsoDays {
|    <# PURE. An ISO 8601 duration (P180D, P1Y, PT8H) as whole days; 0 when it is not one. #>
|    param($Value)
|    if (-not "$Value".Trim()) { return 0 }
|    try { [int][Math]::Floor(([System.Xml.XmlConvert]::ToTimeSpan("$Value".Trim())).TotalDays) } catch { 0 }
|}
|
|function ConvertTo-SIDbInitUtc {
|    <# PURE. A Graph time (text, or the DateTime ConvertFrom-Json made of it) as a UTC DateTime; $null when it is none. #>
|    param($Value)
|    if ($null -eq $Value -or "$Value".Trim() -eq '') { return $null }
|    if ($Value -is [datetime]) { if ($Value.Kind -eq 'Unspecified') { return [datetime]::SpecifyKind($Value, 'Utc') }; return $Value.ToUniversalTime() }
|    try { [datetime]::Parse("$Value", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AdjustToUniversal -bor [Globalization.DateTimeStyles]::AssumeUniversal) } catch { $null }
|}
|
|function Get-SIDbInitPimPolicyLimit {
|    <#
|        Framework §4.5 SQL-ADMIN-GROUP G3: what the group's PIM policy allows for an ACTIVE member assignment made by an admin
|        (its rule Expiration_Admin_Assignment): @{ Known; Permanent; Days; Detail }. Read with RoleManagementPolicy.Read.AzureADGroup
|        (the updater's) or a person's sign-in. Never throws: a policy that cannot be read is Known = $false (then permanent is
|        tried first and 180 days after it, as before).
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$GroupId)
|    $no = [pscustomobject]@{ Known = $false; Permanent = $false; Days = 0; Detail = 'the group''s PIM policy could not be read' }
|    try {
|        $uri = ("https://graph.microsoft.com/v1.0/policies/roleManagementPolicyAssignments?`$filter=scopeId eq '{0}' and scopeType eq 'Group' and roleDefinitionId eq 'member'&`$expand=policy(`$expand=rules)" -f $GroupId)
|        $r = & $Graph 'GET' $uri $null
|        $a = @(Get-SIDbInitProp $r @('value') | Where-Object { $_ })[0]
|        $rule = @(Get-SIDbInitProp $a @('policy', 'rules') | Where-Object { $_ -and [string](Get-SIDbInitProp $_ @('id')) -eq 'Expiration_Admin_Assignment' })[0]
|        if (-not $rule) { return $no }
|        $req = [bool](Get-SIDbInitProp $rule @('isExpirationRequired'))
|        $days = ConvertFrom-SIDbInitIsoDays (Get-SIDbInitProp $rule @('maximumDuration'))
|        if ($req -and $days -le 0) { return $no }
|        [pscustomobject]@{ Known = $true; Permanent = (-not $req); Days = $days
|                           Detail = $(if (-not $req) { 'the group''s PIM policy allows a permanent active assignment' } else { 'the group''s PIM policy allows an active assignment of at most {0} days' -f $days }) }
|    } catch { $no }
|}
|
|function Get-SIDbInitPimAssignment {
|    <#
|        Framework §4.5 SQL-ADMIN-GROUP G4: the identity's ACTIVE PIM-for-Groups member assignment to the group, read from
|        /identityGovernance/privilegedAccess/group/assignmentScheduleInstances (PrivilegedAssignmentSchedule.Read.AzureADGroup).
|        Returns @{ Found; Permanent; End (UTC, $null = permanent); Start; MemberType; AssignmentType } -- the one that lasts
|        longest when there are several. THROWS when the directory cannot be asked.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId)
|    $uri = ("https://graph.microsoft.com/v1.0/identityGovernance/privilegedAccess/group/assignmentScheduleInstances?`$filter=groupId eq '{0}' and principalId eq '{1}'" -f $GroupId, $PrincipalId)
|    $r = & $Graph 'GET' $uri $null
|    $best = $null
|    foreach ($i in @(Get-SIDbInitProp $r @('value') | Where-Object { $_ })) {
|        if ([string](Get-SIDbInitProp $i @('accessId')) -ne 'member') { continue }
|        $end = ConvertTo-SIDbInitUtc (Get-SIDbInitProp $i @('endDateTime'))
|        $o = [pscustomobject]@{ Found = $true; Permanent = ($null -eq $end); End = $end; Start = (ConvertTo-SIDbInitUtc (Get-SIDbInitProp $i @('startDateTime')))
|                                MemberType = [string](Get-SIDbInitProp $i @('memberType')); AssignmentType = [string](Get-SIDbInitProp $i @('assignmentType')) }
|        if (-not $best -or $o.Permanent -or (-not $best.Permanent -and $o.End -gt $best.End)) { $best = $o }
|        if ($best.Permanent) { break }
|    }
|    if ($best) { return $best }
|    [pscustomobject]@{ Found = $false; Permanent = $false; End = $null; Start = $null; MemberType = ''; AssignmentType = '' }
|}
|
|function Test-SIDbInitMembership {
|    <#
|        Is the job's identity a member of the SQL admin group? Asked two ways, so that an identity without directory read
|        rights (the updater: framework §4.5 G5 gives it only the PIM-for-Groups rights) still gets an answer:
|          * the identity's own memberOf (Test-SIDbInitMember), and
|          * its ACTIVE PIM-for-Groups assignment (Get-SIDbInitPimAssignment) -- an active assignment is a membership.
|        Returns @{ Member = $true | $false | $null (neither could be asked, or memberOf could not and there is no PIM
|        assignment: a direct membership is then not known); Via = memberOf | pim | ''; Pim (the assignment or $null);
|        MemberOfError; PimError }. Never throws.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId, [datetime]$NowUtc = [datetime]::UtcNow)
|    $mo = $null; $moErr = ''
|    try { $mo = [bool](Test-SIDbInitMember -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId) } catch { $moErr = [string]$_.Exception.Message }
|    $pa = $null; $paErr = ''
|    try { $pa = Get-SIDbInitPimAssignment -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId } catch { $paErr = [string]$_.Exception.Message }
|    $active = [bool]($pa -and $pa.Found -and ($pa.Permanent -or ($pa.End -and $pa.End -gt $NowUtc.ToUniversalTime())))
|    $member = if ($mo -eq $true -or $active) { $true } elseif ($mo -eq $false) { $false } else { $null }
|    [pscustomobject]@{ Member = $member; Via = $(if ($mo -eq $true) { 'memberOf' } elseif ($active) { 'pim' } else { '' }); Pim = $pa; MemberOfError = $moErr; PimError = $paErr }
|}
|
|function Add-SIDbInitPimMember {
|    <# The active PIM-for-Groups assignment, then READ BACK (the identity's memberOf, or its active PIM assignment: an active
|       assignment is a membership). Framework §4.5 G3: permanent first -- when the group's PIM policy says it is not allowed,
|       the policy's own limit at once (unknown policy: permanent, then 180 days); the end date is SAID. An assignment
|       already there counts as made. Returns @{ State = added | refused; Detail; End }. Never throws. #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId,
|          [scriptblock]$Sleep, [scriptblock]$Print, [int]$LimitSeconds = 300, [datetime]$NowUtc = [datetime]::UtcNow)
|    $uri = 'https://graph.microsoft.com/v1.0/identityGovernance/privilegedAccess/group/assignmentScheduleRequests'
|    $lim = Get-SIDbInitPimPolicyLimit -Graph $Graph -GroupId $GroupId
|    $limDays = if ($lim.Known -and $lim.Days -gt 0) { $lim.Days } else { 180 }
|    $tries = if ($lim.Known -and -not $lim.Permanent) { @($limDays) } else { @(0, $limDays) }
|    $made = ''; $err = ''; $end = $null
|    foreach ($days in $tries) {
|        try {
|            $null = & $Graph 'POST' $uri (Get-SIDbInitPimMemberBody -PrincipalId $PrincipalId -GroupId $GroupId -Days $days -Now $NowUtc)
|            if ($days) { $end = $NowUtc.ToUniversalTime().AddDays($days); $made = ('for {0} days, until {1:yyyy-MM-dd} -- {2}' -f $days, $end, $(if ($lim.Known) { $lim.Detail } else { 'a permanent one was refused' })) } else { $made = 'permanent' }
|            break
|        }
|        catch {
|            $m = [string]$_.Exception.Message
|            if ($m -match 'RoleAssignmentExists|already exists') { $made = 'already assigned'; break }
|            $err = $m
|            if ($m -notmatch 'Expiration|PolicyValidation|ExpirationRule|noExpiration|permanent') { break }   # not a policy limit: no second try
|        }
|    }
|    if (-not $made) { return [pscustomobject]@{ State = 'refused'; Detail = $err; End = $null } }
|    if ($Print) { & $Print ('   PIM-for-Groups: {0} assigned to the SQL admin group as an active member ({1}); waiting until it reads back' -f (Get-SIDbInitNames).Identity, $made) }
|    $waited = 0
|    while ($true) {
|        $mm = Test-SIDbInitMembership -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -NowUtc $NowUtc
|        if ($mm.Member -eq $true) {
|            if ($mm.Pim -and $mm.Pim.Found -and -not $mm.Pim.Permanent) { $end = $mm.Pim.End }
|            return [pscustomobject]@{ State = 'added'; End = $end; Detail = ('{0} is an active PIM-for-Groups member of the SQL admin group ({1}), read back from its {2}' -f (Get-SIDbInitNames).Identity, $made, $(if ($mm.Via -eq 'pim') { 'PIM assignment' } else { 'memberOf' })) }
|        }
|        if ($waited -ge $LimitSeconds) { return [pscustomobject]@{ State = 'refused'; End = $null; Detail = ('the PIM-for-Groups assignment was made ({0}) but the membership did not show within {1} s -- run again later' -f $made, $LimitSeconds) } }
|        if ($Sleep) { & $Sleep 15 }; $waited += 15
|    }
|}
|
|function Get-SIDbInitPimRenewPlan {
|    <# PURE. Framework §4.5 G4: does the membership need a renewal? -Assignment: Get-SIDbInitPimAssignment. Action = none (no
|       PIM assignment -- a direct member -- or a permanent one) | current (it ends after the window) | renew (it is still
|       valid and ends within -WindowDays) | expired (it has ended). Returns @{ Action; End; DaysLeft; Detail }. #>
|    param($Assignment, [datetime]$NowUtc = [datetime]::UtcNow, [int]$WindowDays = 30)
|    $now = $NowUtc.ToUniversalTime()
|    if (-not $Assignment -or -not $Assignment.Found) { return [pscustomobject]@{ Action = 'none'; End = $null; DaysLeft = $null; Detail = 'no PIM-for-Groups assignment (a direct member)' } }
|    if ($Assignment.Permanent -or -not $Assignment.End) { return [pscustomobject]@{ Action = 'none'; End = $null; DaysLeft = $null; Detail = 'a permanent PIM-for-Groups assignment' } }
|    $left = [Math]::Round(($Assignment.End - $now).TotalDays, 1)
|    $endText = $Assignment.End.ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture)
|    if ($left -le 0) { return [pscustomobject]@{ Action = 'expired'; End = $Assignment.End; DaysLeft = $left; Detail = ('the PIM-for-Groups assignment ended {0}' -f $endText) } }
|    if ($left -le $WindowDays) { return [pscustomobject]@{ Action = 'renew'; End = $Assignment.End; DaysLeft = $left; Detail = ('the PIM-for-Groups assignment ends {0} (in {1} days)' -f $endText, $left) } }
|    [pscustomobject]@{ Action = 'current'; End = $Assignment.End; DaysLeft = $left; Detail = ('the PIM-for-Groups assignment ends {0} (in {1} days)' -f $endText, $left) }
|}
|
|function Invoke-SIDbInitPimRenew {
|    <#
|        Framework §4.5 G4: the active PIM-for-Groups assignment RENEWED -- adminExtend (Graph's action for an assignment that
|        is about to end), else adminUpdate (its schedule set again); for one that has ended adminRenew, else a new
|        adminAssign. The new end follows the group's policy (permanent when allowed, else its limit; 180 days when the
|        policy cannot be read). READ BACK: the assignment must end later than before (or be permanent). Returns @{ Ok; Action;
|        End; Detail }. Never throws.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId,
|          $Assignment, [datetime]$NowUtc = [datetime]::UtcNow, [switch]$Expired, [scriptblock]$Sleep, [int[]]$ReadBackWaits = @(5, 15, 30))
|    $uri = 'https://graph.microsoft.com/v1.0/identityGovernance/privilegedAccess/group/assignmentScheduleRequests'
|    $lim = Get-SIDbInitPimPolicyLimit -Graph $Graph -GroupId $GroupId
|    $days = if ($lim.Known -and $lim.Permanent) { 0 } elseif ($lim.Known -and $lim.Days -gt 0) { $lim.Days } else { 180 }
|    $actions = if ($Expired) { @('adminRenew', 'adminAssign') } else { @('adminExtend', 'adminUpdate') }
|    $errs = New-Object System.Collections.Generic.List[string]
|    $done = ''
|    foreach ($a in $actions) {
|        try { $null = & $Graph 'POST' $uri (Get-SIDbInitPimMemberBody -PrincipalId $PrincipalId -GroupId $GroupId -Days $days -Now $NowUtc -Action $a); $done = $a; break }
|        catch { $errs.Add(('{0}: {1}' -f $a, [string]$_.Exception.Message)) }
|    }
|    if (-not $done) { return [pscustomobject]@{ Ok = $false; Action = ''; End = $(if ($Assignment) { $Assignment.End } else { $null }); Detail = ('the renewal was refused ({0})' -f ($errs -join '; ')) } }
|    $before = if ($Assignment -and $Assignment.End) { $Assignment.End } else { [datetime]::MinValue }
|    $last = ''
|    foreach ($w in @(0) + @($ReadBackWaits)) {
|        if ($w -gt 0 -and $Sleep) { & $Sleep $w }
|        try {
|            $after = Get-SIDbInitPimAssignment -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId
|            if ($after.Found -and ($after.Permanent -or ($after.End -and $after.End -gt $before))) {
|                return [pscustomobject]@{ Ok = $true; Action = $done; End = $after.End
|                                          Detail = ('renewed ({0}): the PIM-for-Groups assignment now {1}, read back' -f $done, $(if ($after.Permanent) { 'is permanent' } else { 'ends ' + $after.End.ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture) })) }
|            }
|        } catch { $last = [string]$_.Exception.Message }
|    }
|    [pscustomobject]@{ Ok = $false; Action = $done; End = $(if ($Assignment) { $Assignment.End } else { $null }); Detail = ('the renewal ({0}) was accepted, but the assignment does not read back with a later end{1}' -f $done, $(if ($last) { ' (' + $last + ')' } else { '' })) }
|}
|
|function Sync-SIDbInitMembership {
|    <#
|        Framework §4.5 SQL-ADMIN-GROUP G2-G4 -- THE ONE PATH setup (the guided install, setup\Start-SIDbInitJob.ps1) and the
|        updater use for the job identity's membership of the SQL admin group:
|          1. READ it (Test-SIDbInitMembership: memberOf, or an active PIM-for-Groups assignment);
|          2. not a member -> CONVERGED (Add-SIDbInitMember: direct members/$ref, else an active PIM-for-Groups assignment,
|             permanent first, else the policy's limit with the end date said), read back;
|          3. a member through a PIM assignment that ends within -WindowDays (30) -> RENEWED (Invoke-SIDbInitPimRenew), read
|             back. A renewal that fails while the assignment is still valid is Renewal.State 'failed' -- the CALLER says it as a
|             warning; it never stops anything on its own.
|        Returns @{ State = already | added | refused; Member ($true | $false | $null); JustAdded; Via; End; Renewal @{ State =
|        none | current | renewed | failed | unknown; End; Detail }; Detail }. Never throws.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$GroupId,
|          [scriptblock]$Sleep, [scriptblock]$Print, [int]$LimitSeconds = 300, [int]$WindowDays = -1, [datetime]$NowUtc = [datetime]::UtcNow)
|    if ($WindowDays -lt 0) { $WindowDays = (Get-SIDbInitNames).RenewWindowDays }
|    $id = (Get-SIDbInitNames).Identity
|    $ren = { param($st, $end, $d) [pscustomobject]@{ State = $st; End = $end; Detail = [string]$d } }
|    try {
|        $m = Test-SIDbInitMembership -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -NowUtc $NowUtc
|        $state = 'already'; $just = $false; $detail = ''
|        if ($m.Member -ne $true) {
|            $a = Add-SIDbInitMember -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -Sleep $Sleep -Print $Print -LimitSeconds $LimitSeconds -NowUtc $NowUtc
|            if ([string]$a.State -notin 'already', 'added') {
|                return [pscustomobject]@{ State = 'refused'; Member = $m.Member; JustAdded = $false; Via = ''; End = $null; Renewal = (& $ren 'unknown' $null 'not a member'); Detail = [string]$a.Detail }
|            }
|            $state = [string]$a.State; $just = ($state -eq 'added'); $detail = [string]$a.Detail
|            $m2 = Test-SIDbInitMembership -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -NowUtc $NowUtc
|            if ($m2.Member -eq $true) { $m = $m2 } else { $m = [pscustomobject]@{ Member = $true; Via = 'added'; Pim = $m2.Pim; MemberOfError = $m2.MemberOfError; PimError = $m2.PimError } }
|        } else {
|            $detail = '{0} is a member of the SQL admin group (read from its {1})' -f $id, $(if ($m.Via -eq 'pim') { 'active PIM-for-Groups assignment' } else { 'memberOf' })
|        }
|        # 3. the renewal (only a PIM assignment ends; a direct or permanent membership needs none)
|        $plan = Get-SIDbInitPimRenewPlan -Assignment $m.Pim -NowUtc $NowUtc -WindowDays $WindowDays
|        $r = switch ($plan.Action) {
|            'renew' {
|                $x = Invoke-SIDbInitPimRenew -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -Assignment $m.Pim -NowUtc $NowUtc -Sleep $Sleep
|                & $ren $(if ($x.Ok) { 'renewed' } else { 'failed' }) $x.End ('{0}; {1}' -f $plan.Detail, $x.Detail)
|            }
|            'expired' {
|                # memberOf still shows it (replication) but the assignment has ended: renewed as one that has ended
|                $x = Invoke-SIDbInitPimRenew -Graph $Graph -PrincipalId $PrincipalId -GroupId $GroupId -Assignment $m.Pim -NowUtc $NowUtc -Sleep $Sleep -Expired
|                & $ren $(if ($x.Ok) { 'renewed' } else { 'failed' }) $x.End ('{0}; {1}' -f $plan.Detail, $x.Detail)
|            }
|            'current' { & $ren 'current' $plan.End $plan.Detail }
|            default   { & $ren $(if ($m.PimError -and -not $m.Pim) { 'unknown' } else { 'none' }) $null $(if ($m.PimError -and -not $m.Pim) { 'its PIM-for-Groups assignment could not be read: ' + $m.PimError } else { $plan.Detail }) }
|        }
|        [pscustomobject]@{ State = $state; Member = $true; JustAdded = $just; Via = [string]$m.Via; End = $r.End; Renewal = $r; Detail = $detail }
|    } catch {
|        [pscustomobject]@{ State = 'refused'; Member = $null; JustAdded = $false; Via = ''; End = $null; Renewal = (& $ren 'unknown' $null ''); Detail = ('the membership could not be checked: {0}' -f $_.Exception.Message) }
|    }
|}
|
|function New-SIDbInitMembershipRecordValue {
|    <# PURE. The membership's own row (cfg.InstallState 'DbJobMembership', <= 400 characters): { state ok | renewal-failed |
|       gone | missing, at, end?, via?, why? } -- the heartbeat's setup step db-job reads it (Get-SISetupSteps). #>
|    param([Parameter(Mandatory)][ValidateSet('ok', 'renewal-failed', 'gone', 'missing')][string]$State, $End = $null, [string]$Via = '', [string]$Why = '', [datetime]$NowUtc = [datetime]::UtcNow)
|    $inv = [Globalization.CultureInfo]::InvariantCulture
|    $o = [ordered]@{ state = $State; at = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) }
|    if ($End -is [datetime]) { $o.end = $End.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) }
|    if ($Via) { $o.via = $Via }
|    $w = [regex]::Replace([regex]::Replace("$Why", '[\x00-\x1F]', ' '), '\s+', ' ').Trim()
|    if ($w.Length -gt 250) { $w = $w.Substring(0, 247).TrimEnd() + '...' }
|    if ($w) { $o.why = $w }
|    $v = ConvertTo-Json -InputObject $o -Compress
|    while ($v.Length -gt (Get-SIDbInitNames).RecordMax -and $w.Length -gt 10) { $w = $w.Substring(0, $w.Length - 20).TrimEnd() + '...'; $o.why = $w; $v = ConvertTo-Json -InputObject $o -Compress }
|    $v
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|#  Framework §4.5 SQL-ADMIN-GROUP G5: the UPDATER identity's Microsoft Graph application permissions -- exactly the three
|#  PIM-for-Groups rights, granted by SETUP (the person or app running it holds the right to grant application permissions)
|#  and only CHECKED by the updater (it cannot grant itself). The directory-wide role-management write right is refused by
|#  name (least privilege, decided): it is never asked for, never granted here.
|# ---------------------------------------------------------------------------------------------------------------------
|
|function Get-SIDbInitGraphAppId { <# PURE. Microsoft Graph's application id (the same in every tenant). #> '00000003-0000-0000-c000-000000000000' }
|
|function Get-SIDbInitUpdaterGraphRoleNames {
|    <# PURE. G5: the updater identity's Microsoft Graph application permissions, by VALUE (their ids are read from Graph's own
|       service principal at run time -- never written here). Required = $false: taken only when Graph has it. #>
|    @(
|        [pscustomobject]@{ Value = 'PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup'; Required = $true;  Why = 'make and renew the database setup job identity''s active PIM-for-Groups membership' }
|        [pscustomobject]@{ Value = 'PrivilegedAssignmentSchedule.Read.AzureADGroup';      Required = $false; Why = 'read that membership and its end date' }
|        [pscustomobject]@{ Value = 'RoleManagementPolicy.Read.AzureADGroup';              Required = $true;  Why = 'read the group''s PIM policy (permanent, or its longest duration)' }
|        # framework §4.5 G5 (added 2026-11-05): read only -- without it the read-back of the membership (the identity's
|        # memberOf) is refused and reads "unknown"
|        [pscustomobject]@{ Value = 'GroupMember.Read.All';                                Required = $true;  Why = 'read the membership back (the identity''s memberOf)' }
|        # framework §4.5 G5 (added 2026-11-05): read only -- servicePrincipals/{id}/memberOf (the member side of the read-back)
|        # needs it on top of GroupMember.Read.All
|        [pscustomobject]@{ Value = 'Application.Read.All';                                Required = $true;  Why = 'read the identity''s own memberOf back (the member side)' }
|    )
|}
|
|function Get-SIDbInitRefusedGraphRoleNames {
|    <# PURE. G5 (decided, least privilege): application permissions the updater identity is NEVER given by SecurityInsight. #>
|    @('RoleManagement.ReadWrite.Directory')
|}
|
|function Resolve-SIDbInitUpdaterGraphRoles {
|    <# PURE. -GraphSp: Microsoft Graph's service principal with its appRoles. Each G5 permission with its id found BY VALUE
|       among the roles an application may hold (allowedMemberTypes Application) -- @{ Value; Id; Required; Found; Why }.
|       -Roles: a subset of the G5 list (a test seam); anything outside it -- above all a refused one -- THROWS. #>
|    param([Parameter(Mandatory)]$GraphSp, [string[]]$Roles = @())
|    $all = @(Get-SIDbInitUpdaterGraphRoleNames)
|    $want = if (@($Roles | Where-Object { $_ }).Count) {
|        foreach ($r in $Roles) {
|            if ((Get-SIDbInitRefusedGraphRoleNames) -contains $r) { throw ("'{0}' is never given to the updater identity (least privilege: only the PIM-for-Groups permissions)" -f $r) }
|            if (-not @($all | Where-Object { $_.Value -eq $r }).Count) { throw ("'{0}' is not one of the updater identity's Microsoft Graph permissions" -f $r) }
|        }
|        @($all | Where-Object { $Roles -contains $_.Value })
|    } else { $all }
|    $appRoles = @(Get-SIDbInitProp $GraphSp @('appRoles') | Where-Object { $_ })
|    foreach ($w in $want) {
|        $hit = @($appRoles | Where-Object { [string](Get-SIDbInitProp $_ @('value')) -ceq $w.Value -and @(Get-SIDbInitProp $_ @('allowedMemberTypes')) -contains 'Application' })[0]
|        [pscustomobject]@{ Value = $w.Value; Id = $(if ($hit) { [string](Get-SIDbInitProp $hit @('id')) } else { '' }); Required = [bool]$w.Required; Found = [bool]$hit; Why = $w.Why }
|    }
|}
|
|function Get-SIDbInitHeldAppRoleIds {
|    <# The appRoleIds -PrincipalId holds on -ResourceId (its appRoleAssignments, every page). THROWS when they cannot be read. #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$ResourceId)
|    $out = New-Object System.Collections.Generic.List[string]
|    $next = 'https://graph.microsoft.com/v1.0/servicePrincipals/{0}/appRoleAssignments' -f $PrincipalId
|    for ($i = 0; $next -and $i -lt 20; $i++) {
|        $page = & $Graph 'GET' $next $null
|        foreach ($a in @(Get-SIDbInitProp $page @('value') | Where-Object { $_ })) {
|            if ([string](Get-SIDbInitProp $a @('resourceId')) -eq $ResourceId) { $out.Add(([string](Get-SIDbInitProp $a @('appRoleId'))).ToLowerInvariant()) }
|        }
|        $next = [string](Get-SIDbInitProp $page @('@odata.nextLink'))
|    }
|    $out.ToArray()   # enumerated: wrap the call in @( )
|}
|
|function Grant-SIDbInitUpdaterGraphRoles {
|    <#
|        SETUP (the guided install's step db-job, setup\Start-SIDbInitJob.ps1): the updater identity (-PrincipalId, its service
|        principal's object id) given the G5 Microsoft Graph application permissions -- ids resolved from Graph's own service
|        principal by value, only what is missing granted (POST servicePrincipals/{id}/appRoleAssignments), every one READ
|        BACK. A "not found" on an identity made minutes ago is tried again (-NotYetWaits). Returns @{ Ok; Granted; Present;
|        Missing; Lines; Detail }. Never throws.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$PrincipalId, [string[]]$Roles = @(),
|          [scriptblock]$Sleep, [int[]]$NotYetWaits = @(10, 20, 30, 45, 60))
|    $lines = New-Object System.Collections.Generic.List[string]
|    $granted = New-Object System.Collections.Generic.List[string]; $present = New-Object System.Collections.Generic.List[string]; $missing = New-Object System.Collections.Generic.List[string]
|    $out = { param($ok, $d) [pscustomobject]@{ Ok = [bool]$ok; Granted = $granted.ToArray(); Present = $present.ToArray(); Missing = $missing.ToArray(); Lines = $lines.ToArray(); Detail = [string]$d } }
|    try {
|        $sp = @(Get-SIDbInitProp (& $Graph 'GET' ("https://graph.microsoft.com/v1.0/servicePrincipals?`$filter=appId eq '{0}'&`$select=id,appId,appRoles" -f (Get-SIDbInitGraphAppId)) $null) @('value') | Where-Object { $_ })[0]
|        if (-not $sp -or -not [string](Get-SIDbInitProp $sp @('id'))) { return (& $out $false 'Microsoft Graph''s service principal was not found in this tenant') }
|        $want = @(Resolve-SIDbInitUpdaterGraphRoles -GraphSp $sp -Roles $Roles)
|        foreach ($w in @($want | Where-Object { -not $_.Found })) {
|            if ($w.Required) { $missing.Add($w.Value); $lines.Add(('Microsoft Graph has no application permission {0} -- it cannot be granted' -f $w.Value)) }
|            else { $lines.Add(('Microsoft Graph has no separate application permission {0} -- not needed (the read-write one reads too)' -f $w.Value)) }
|        }
|        $want = @($want | Where-Object { $_.Found })
|        foreach ($w in $want) { if ((Get-SIDbInitRefusedGraphRoleNames) -contains $w.Value) { throw ('{0} is never granted to the updater identity' -f $w.Value) } }
|        $spId = [string](Get-SIDbInitProp $sp @('id'))
|        $held = @(Get-SIDbInitHeldAppRoleIds -Graph $Graph -PrincipalId $PrincipalId -ResourceId $spId)
|        foreach ($w in $want) {
|            if ($held -contains $w.Id.ToLowerInvariant()) { $present.Add($w.Value); continue }
|            $tries = 0; $done = $false; $why = ''
|            while (-not $done) {
|                try {
|                    $null = & $Graph 'POST' ('https://graph.microsoft.com/v1.0/servicePrincipals/{0}/appRoleAssignments' -f $PrincipalId) ([ordered]@{ principalId = $PrincipalId; resourceId = $spId; appRoleId = $w.Id })
|                    $done = $true; $granted.Add($w.Value)
|                } catch {
|                    $why = [string]$_.Exception.Message
|                    if ($why -match '(?i)already exist') { $done = $true; $present.Add($w.Value); break }
|                    $notYet = ($why -match '(?i)\b404\b|Request_ResourceNotFound|does not exist|not found') -and ($why -notmatch '(?i)\b403\b|Authorization_RequestDenied|Insufficient privileges|Forbidden')
|                    if (-not $notYet -or $tries -ge @($NotYetWaits).Count) { break }
|                    if ($Sleep) { & $Sleep ([int]$NotYetWaits[$tries]) }; $tries++
|                }
|            }
|            if (-not $done) { $missing.Add($w.Value); $lines.Add(('{0}: not granted ({1})' -f $w.Value, $why)) }
|        }
|        # READ BACK: what the directory HAS, not the requests it accepted
|        if ($granted.Count) {
|            $back = @(Get-SIDbInitHeldAppRoleIds -Graph $Graph -PrincipalId $PrincipalId -ResourceId $spId)
|            foreach ($w in @($want | Where-Object { $granted -contains $_.Value })) {
|                if ($back -notcontains $w.Id.ToLowerInvariant()) { $missing.Add($w.Value); $lines.Add(('{0}: granted, but it does not read back' -f $w.Value)) }
|            }
|        }
|        $ok = ($missing.Count -eq 0)
|        $d = if ($ok) { 'the updater identity holds the Microsoft Graph application permissions {0} (read back{1})' -f ((@($want | ForEach-Object Value)) -join ', '), $(if ($granted.Count) { '; granted now: ' + ($granted -join ', ') } else { '' }) }
|             else { 'the updater identity does not hold {0} -- an Entra administrator grants them (Privileged Role Administrator, or the right to grant application permissions); then run setup again' -f ($missing -join ', ') }
|        & $out $ok $d
|    } catch {
|        $missing.Add('(not read)')
|        & $out $false ('the updater identity''s Microsoft Graph permissions could not be read or granted: {0}' -f $_.Exception.Message)
|    }
|}
|
|function Get-SIDbInitTokenRoles {
|    <# PURE. The application permissions (roles claim) and object id (oid) in an access token -- what the token's holder may do,
|       read without any directory right. $null when it is not a token. #>
|    param([AllowEmptyString()][string]$Token)
|    $p = ("$Token" -split '\.')
|    if ($p.Count -lt 2 -or -not $p[1]) { return $null }
|    $s = $p[1].Replace('-', '+').Replace('_', '/')
|    switch ($s.Length % 4) { 2 { $s += '==' } 3 { $s += '=' } }
|    $o = $null
|    try { $o = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($s)) | ConvertFrom-Json -ErrorAction Stop } catch { return $null }
|    [pscustomobject]@{ Roles = @(@(Get-SIDbInitProp $o @('roles')) | Where-Object { $_ } | ForEach-Object { [string]$_ }); ObjectId = [string](Get-SIDbInitProp $o @('oid')) }
|}
|
|function Test-SIDbInitUpdaterGraphRoles {
|    <# PURE. G5, the UPDATER's side: the permissions its own Graph token carries (-Held, the roles claim) against the G5 list.
|       Missing = a required one it does not hold. A refused one it holds is said too (more than it needs). Returns @{ Ok;
|       Missing; Extra; Lines }. The updater cannot grant itself: every line names who grants it. #>
|    param([AllowNull()][string[]]$Held)
|    $h = @($Held | Where-Object { $_ })
|    $missing = @(Get-SIDbInitUpdaterGraphRoleNames | Where-Object { $_.Required -and $h -notcontains $_.Value } | ForEach-Object Value)
|    $extra = @(Get-SIDbInitRefusedGraphRoleNames | Where-Object { $h -contains $_ })
|    $lines = New-Object System.Collections.Generic.List[string]
|    if ($missing.Count) { $lines.Add(('WARNING: the updater identity does not hold the Microsoft Graph application permission(s) {0}, so it cannot keep the database setup job''s membership of the SQL admin group current -- setup grants them (the guided install, or setup\Start-SIDbInitJob.ps1 through the Support app); the update goes on' -f ($missing -join ', '))) }
|    if ($extra.Count) { $lines.Add(('WARNING: the updater identity holds {0}, more than it needs -- an Entra administrator removes it (it needs only the PIM-for-Groups permissions)' -f ($extra -join ', '))) }
|    [pscustomobject]@{ Ok = ($missing.Count -eq 0); Missing = $missing; Extra = $extra; Lines = $lines.ToArray() }
|}
|
|function Get-SIDbInitAdminGroupId {
|    <# PURE. The SQL server's Entra administrator as a group id ('' when it is not a group: then no identity can be an admin
|       through it -- setup\Set-SISqlAdminGroup.ps1 makes the group the administrator). -Server: the server as ARM returns it. #>
|    param($Server)
|    $a = Get-SIDbInitProp $Server @('properties', 'administrators')
|    if (-not $a) { return '' }
|    $t = [string](Get-SIDbInitProp $a @('principalType'))
|    if ($t -and $t -ne 'Group') { return '' }
|    [string](Get-SIDbInitProp $a @('sid'))
|}
|
|function Wait-SIDbInitExecution {
|    <# ARM: the execution's own status until it ends (Succeeded / Failed / Stopped / Degraded) or -TimeoutSeconds. Returns
|       @{ Status; Seconds }. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$JobId, [Parameter(Mandatory)][string]$Execution,
|          [int]$TimeoutSeconds = 1500, [int]$PollSeconds = 15, [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s })
|    $waited = 0
|    while ($true) {
|        $e = $null
|        try { $e = & $Arm 'GET' ('{0}/executions/{1}?api-version={2}' -f $JobId, $Execution, (Get-SIDbInitNames).AppApi) $null } catch { $e = $null }
|        $st = [string](Get-SIDbInitProp $e @('properties', 'status'))
|        if ($st -in 'Succeeded', 'Failed', 'Stopped', 'Degraded') { return [pscustomobject]@{ Status = $st; Seconds = $waited } }
|        if ($waited -ge $TimeoutSeconds) { return [pscustomobject]@{ Status = 'TimedOut'; Seconds = $waited } }
|        & $Sleep $PollSeconds; $waited += $PollSeconds
|    }
|}
|
|function New-SIDbInitRunId { <# A short run id the job records, so a caller knows the row is from ITS start. #> ([guid]::NewGuid().ToString('N')).Substring(0, 12) }
|
|function Set-SIDbInitIdentity {
|    <# The job's identity in the install's resource group: read, made when it is not there (ARM PUT), read back until it has
|       its client and principal id. Returns @{ Ok; Made; Id; ClientId; PrincipalId; Problem }. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup,
|          [Parameter(Mandatory)][string]$Location, [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s })
|    $n = Get-SIDbInitNames
|    $path = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{2}?api-version={3}' -f $SubscriptionId, $ResourceGroup, $n.Identity, $n.MiApi
|    $made = $false
|    $mi = & $Arm 'GET' $path $null
|    if (-not $mi) {
|        $tags = [ordered]@{ product = 'securityinsight' }; $tags[$n.TagName] = $n.TagValue
|        $mi = & $Arm 'PUT' $path ([ordered]@{ location = $Location; tags = $tags })
|        $made = $true
|    }
|    for ($i = 0; $i -lt 6 -and -not ([string](Get-SIDbInitProp $mi @('properties', 'clientId')) -and [string](Get-SIDbInitProp $mi @('properties', 'principalId'))); $i++) {
|        & $Sleep 5; $mi = & $Arm 'GET' $path $null
|    }
|    $cid = [string](Get-SIDbInitProp $mi @('properties', 'clientId')); $pid_ = [string](Get-SIDbInitProp $mi @('properties', 'principalId'))
|    if (-not $cid -or -not $pid_) { return [pscustomobject]@{ Ok = $false; Made = $made; Id = ''; ClientId = ''; PrincipalId = ''; Problem = ('the identity {0} has no client / principal id yet' -f $n.Identity) } }
|    [pscustomobject]@{ Ok = $true; Made = $made; Id = [string](Get-SIDbInitProp $mi @('id')); ClientId = $cid; PrincipalId = $pid_; Problem = '' }
|}
|
|function Set-SIDbInitJob {
|    <# The job made or brought to -Body (ARM PUT -- idempotent), read back until it is provisioned. Returns @{ Ok; JobId; Job;
|       Problem }. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup,
|          [Parameter(Mandatory)]$Body, [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s })
|    $n = Get-SIDbInitNames
|    $id = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.App/jobs/{2}' -f $SubscriptionId, $ResourceGroup, $n.Job
|    $path = '{0}?api-version={1}' -f $id, $n.AppApi
|    $null = & $Arm 'PUT' $path $Body
|    $job = $null
|    for ($i = 0; $i -lt 30; $i++) {
|        $job = & $Arm 'GET' $path $null
|        $ps = [string](Get-SIDbInitProp $job @('properties', 'provisioningState'))
|        if ($job -and ($ps -in 'Succeeded', 'Failed', 'Canceled' -or -not $ps)) { break }
|        & $Sleep 10
|    }
|    $ps = [string](Get-SIDbInitProp $job @('properties', 'provisioningState'))
|    if (-not $job -or $ps -in 'Failed', 'Canceled') { return [pscustomobject]@{ Ok = $false; JobId = $id; Job = $job; Problem = ('the job {0} was not made (Azure shows: {1})' -f $n.Job, $(if ($ps) { $ps } else { 'nothing' })) } }
|    [pscustomobject]@{ Ok = $true; JobId = $id; Job = $job; Problem = '' }
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|#  (live 2026-11-07, install-a): a support start of the job BESIDE a running update overwrote the result the update waited for,
|#  and its grants met the update's in a deadlock. Every support start of the job (setup\Start-SIDbInitJob.ps1, its
|#  grants-only run, and Grant-SISupportAppDatabase.ps1 which sends the same kind of grants itself) REFUSES while the updater
|#  runs -- a running execution of the updater job, or a lock row the updater beats -- and says to start it after the update.
|# ---------------------------------------------------------------------------------------------------------------------
|
|function Get-SIDbInitUpdaterLockSql {
|    <# PURE. READ ONLY, one scalar: the lock row an updater run beats now ('<lock>|<holder>|<last beat>'; NULL = none, or no
|       lock table). An updater run holds the 'updater' row from its start, and the 'install' row from its run gate on. #>
|    $m = [int](Get-SIDbInitNames).UpdaterLockStaleMinutes
|    "SET NOCOUNT ON; IF OBJECT_ID(N'cfg.PipelineLock') IS NULL SELECT CAST(NULL AS nvarchar(400)) AS Held; ELSE SELECT TOP (1) LockId + N'|' + Holder + N'|' + ISNULL(CONVERT(nvarchar(19), HeartbeatUtc, 126) + N'Z', N'') AS Held FROM cfg.PipelineLock WHERE Holder LIKE N'caj-si-updater%' AND HeartbeatUtc >= DATEADD(minute, -$m, SYSUTCDATETIME()) ORDER BY HeartbeatUtc DESC;"
|}
|
|function Get-SIDbInitUpdaterRunning {
|    <# PURE. The updater execution that runs now among -Executions (ARM shape: name, properties.status / startTime / endTime):
|       Running / Processing, no end, started within -LimitSeconds (an older one is a leftover). @{ Name; StartedUtc } or $null. #>
|    param([object[]]$Executions = @(), [Parameter(Mandatory)][datetime]$NowUtc, [int]$LimitSeconds = 0)
|    if ($LimitSeconds -le 0) { $LimitSeconds = [int](Get-SIDbInitNames).UpdaterLimitSeconds }
|    $styles = [Globalization.DateTimeStyles]'AdjustToUniversal, AssumeUniversal'
|    foreach ($e in @($Executions | Where-Object { $_ })) {
|        $st = [string](Get-SIDbInitProp $e @('properties', 'status'))
|        if ($st -notin 'Running', 'Processing') { continue }
|        if ([string](Get-SIDbInitProp $e @('properties', 'endTime'))) { continue }
|        $s = $null; $t = [string](Get-SIDbInitProp $e @('properties', 'startTime'))
|        if ($t) { $d = [datetime]::MinValue; if ([datetime]::TryParse($t, [Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { $s = $d } }
|        if ($s -and ($NowUtc.ToUniversalTime() - $s).TotalSeconds -gt ($LimitSeconds + 900)) { continue }
|        return [pscustomobject]@{ Name = [string](Get-SIDbInitProp $e @('name')); StartedUtc = $s }
|    }
|    $null
|}
|
|function Test-SIDbInitUpdaterBusy {
|    <#
|        #1146: does the updater run now? (1) -LockText: what Get-SIDbInitUpdaterLockSql answered ('' = no row, $null = not
|        read here); (2) ARM, when -Arm is given: the updater job(s) of the resource group (caj-si-updater, or a job named
|        *-updater) and their executions. Returns @{ Busy; Why; Read (what was looked at) }. A part that cannot be read is said
|        in Read and does not count as busy (a support repair is never blocked by a read that failed).
|    #>
|    param([scriptblock]$Arm, [string]$SubscriptionId = '', [string]$ResourceGroup = '', [AllowNull()][AllowEmptyString()][string]$LockText = $null,
|          [datetime]$NowUtc = [datetime]::UtcNow)
|    $n = Get-SIDbInitNames
|    $read = New-Object System.Collections.Generic.List[string]
|    $busy = { param($why) [pscustomobject]@{ Busy = $true; Why = $why; Read = $read.ToArray() } }
|    if ($null -ne $LockText) {
|        $parts = "$LockText".Split('|')
|        if ("$LockText".Trim() -and $parts.Count -ge 2) {
|            return (& $busy ('the updater runs now: it holds the install''s lock row ''{0}'' ({1}, last sign of life {2})' -f $parts[0], $parts[1], $(if ($parts.Count -ge 3 -and $parts[2]) { $parts[2] } else { '?' })))
|        }
|        $read.Add('the lock rows: no updater holds one')
|    }
|    if ($Arm -and $SubscriptionId -and $ResourceGroup) {
|        try {
|            $base = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.App/jobs' -f $SubscriptionId, $ResourceGroup
|            $jobs = New-Object System.Collections.Generic.List[object]
|            $next = '{0}?api-version={1}' -f $base, $n.AppApi
|            for ($i = 0; $next -and $i -lt 20; $i++) {
|                $page = & $Arm 'GET' $next $null
|                if (-not $page) { break }
|                foreach ($j in @(Get-SIDbInitProp $page @('value'))) { if ($j) { $jobs.Add($j) } }
|                $next = [string](Get-SIDbInitProp $page @('nextLink'))
|            }
|            $upd = @($jobs | Where-Object { [string](Get-SIDbInitProp $_ @('name')) -match '(?i)^caj-si-updater$|-updater$' })
|            if (-not $upd.Count) { $read.Add('the updater job: not found in the resource group') }
|            foreach ($u in $upd) {
|                $un = [string](Get-SIDbInitProp $u @('name'))
|                $limit = 0; try { $limit = [int](Get-SIDbInitProp $u @('properties', 'configuration', 'replicaTimeout')) } catch { $limit = 0 }
|                $ex = & $Arm 'GET' ('{0}/{1}/executions?api-version={2}' -f $base, $un, $n.AppApi) $null
|                $hit = Get-SIDbInitUpdaterRunning -Executions @(Get-SIDbInitProp $ex @('value')) -NowUtc $NowUtc -LimitSeconds $limit
|                if ($hit) {
|                    return (& $busy ('the updater runs now: {0} execution {1}{2}' -f $un, $hit.Name, $(if ($hit.StartedUtc) { ' (started {0:yyyy-MM-dd HH:mm}Z)' -f $hit.StartedUtc } else { '' })))
|                }
|                $read.Add(('the updater job {0}: no execution runs' -f $un))
|            }
|        } catch { $read.Add(('the updater''s executions could not be read ({0})' -f $_.Exception.Message)) }
|    }
|    [pscustomobject]@{ Busy = $false; Why = ''; Read = $read.ToArray() }
|}
|
|function Get-SIDbInitUpdaterBusyText {
|    <# PURE. The refusal's one line (the same words in every script that starts the job). #>
|    param([Parameter(Mandatory)][string]$Why, [string]$What = 'the database setup job')
|    ('REFUSED: {0} -- {1} is not started beside it (a run beside the update overwrites the result the update waits for, and its grants can meet the update''s in a deadlock). Start it again after the update has ended. Nothing was changed.' -f $Why, $What)
|}
|
|function Start-SIDbInitRun {
|    <# ONE run: started with -Env on top of the job's own environment (the run id, who started it, the Support app), waited
|       for. Returns @{ Ok (the execution Succeeded -- the job exits 0 only when every identity read back); Status; Execution;
|       Run; Seconds; Why }. #1146: a SUPPORT start is refused while the updater runs (Test-SIDbInitUpdaterBusy over the job's
|       resource group): Status 'Refused', nothing started, Why says it. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$JobId, [Parameter(Mandatory)]$Job, [Parameter(Mandatory)][ValidateSet('installer', 'updater', 'support')][string]$By,
|          [string]$Support = '', [int]$TimeoutSeconds = 1500, [int]$PollSeconds = 15, [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s },
|          [ValidateSet('all', 'grants')][string]$Steps = 'all',
|          # more per-execution variables (the identity move: SI_DBINIT_MOVES / SI_DBINIT_DROPS and today's SI_DBINIT_PRINCIPALS)
|          [System.Collections.IDictionary]$Extra = @{})
|    if ($By -eq 'support' -and $JobId -match '^/subscriptions/(?<s>[^/]+)/resourceGroups/(?<g>[^/]+)/') {
|        $b = Test-SIDbInitUpdaterBusy -Arm $Arm -SubscriptionId $Matches['s'] -ResourceGroup $Matches['g']
|        if ($b.Busy) { return [pscustomobject]@{ Ok = $false; Status = 'Refused'; Execution = ''; Run = ''; Seconds = 0; Why = (Get-SIDbInitUpdaterBusyText -Why $b.Why) } }
|    }
|    $run = New-SIDbInitRunId
|    $env = [ordered]@{ SI_DBINIT_RUN = $run; SI_DBINIT_BY = $By; SI_DBINIT_STEPS = $Steps }
|    if ($Support) { $env.SI_DBINIT_SUPPORT = $Support }
|    foreach ($k in @($Extra.Keys)) { if ([string]$k -match '^SI_DBINIT_(MOVES|DROPS|PRINCIPALS|SUPPORT_STANDING_OFF)$') { $env[[string]$k] = [string]$Extra[$k] } }
|    $start = & $Arm 'POST' ('{0}/start?api-version={1}' -f $JobId, (Get-SIDbInitNames).AppApi) (Get-SIDbInitStartBody -Job $Job -Env $env)
|    $exec = [string](Get-SIDbInitProp $start @('name')); if (-not $exec) { $exec = (([string](Get-SIDbInitProp $start @('id'))) -split '/')[-1] }
|    if (-not $exec) { return [pscustomobject]@{ Ok = $false; Status = 'NotStarted'; Execution = ''; Run = $run; Seconds = 0; Why = '' } }
|    $w = Wait-SIDbInitExecution -Arm $Arm -JobId $JobId -Execution $exec -TimeoutSeconds $TimeoutSeconds -PollSeconds $PollSeconds -Sleep $Sleep
|    [pscustomobject]@{ Ok = ($w.Status -eq 'Succeeded'); Status = $w.Status; Execution = $exec; Run = $run; Seconds = $w.Seconds; Why = '' }
|}
|
|function Resolve-SIDbInitSupportAppId {
|    <#
|        PURE. Which Support app a support run of the job gives database access to (found live 2026-11-05: a client id typed
|        by hand was ANOTHER tenant's Support app -- the Invardia Support app has a different client id in every customer
|        tenant; the open Support session knows this tenant's). -Typed: what the caller gave ('' = nothing). -SessionAppId:
|        the Support session's AppId ('' = no session, or it names none). No typed id -> the session's. A typed id that is
|        not the session's -> REFUSED. A typed id without a session to compare with -> as typed. Returns @{ Ok; AppId; Why }.
|    #>
|    param([AllowEmptyString()][string]$Typed = '', [AllowEmptyString()][string]$SessionAppId = '')
|    $g = [guid]::Empty; $t = [guid]::Empty
|    $sess = if ([guid]::TryParse("$SessionAppId".Trim(), [ref]$g) -and $g -ne [guid]::Empty) { $g.ToString() } else { '' }
|    $typedId = "$Typed".Trim()
|    if (-not $typedId) { return [pscustomobject]@{ Ok = $true; AppId = $sess; Why = $(if ($sess) { 'the Support session''s own Support app' } else { '' }) } }
|    if (-not [guid]::TryParse($typedId, [ref]$t)) { return [pscustomobject]@{ Ok = $false; AppId = ''; Why = ('-SupportAppId {0} is not a client id' -f $typedId) } }
|    if ($sess -and $t.ToString() -ne $sess) {
|        return [pscustomobject]@{ Ok = $false; AppId = ''; Why = ('-SupportAppId {0} is not the Support app of this tenant''s Support session ({1}). The Invardia Support app has a different client id in every tenant, and a user made from another tenant''s id is a user nobody can sign in as. Leave -SupportAppId out (the session''s own is used) or give {1}.' -f $t.ToString(), $sess) }
|    }
|    [pscustomobject]@{ Ok = $true; AppId = $t.ToString(); Why = $(if ($sess) { 'the Support session''s own Support app' } else { 'as given (no Support session to compare it with)' }) }
|}
|
|function Get-SIDbInitLogText {
|    <# PURE. Where a run's lines are, in plain words (a portal path; never a command). #>
|    param([string]$ResourceGroup, [string]$Execution)
|    'Azure portal: Container Apps jobs > {0} (resource group {1}) > Execution history > {2} > Console logs' -f (Get-SIDbInitNames).Job, $ResourceGroup, $(if ($Execution) { $Execution } else { 'the latest run' })
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|#  Framework §4.5 SQL-ADMIN-GROUP G3a: a managed identity's token keeps its old group claims for up to ~24 hours. Moving the
|#  SQL server's administrator from one GROUP to ANOTHER (setup\Set-SISqlAdminGroup.ps1 -ReplaceCurrentAdminGroup) would lock
|#  the database setup job out until its token is renewed. So such a move is PROVEN: right after it the job must sign in
|#  THROUGH the new group (one run, started again after a growing wait); otherwise the server's administrator is put back
|#  automatically, as it was, and read back. A membership of the new group that is 24 hours old needs no proof.
|# ---------------------------------------------------------------------------------------------------------------------
|
|function Get-SISqlAdminMovePlan {
|    <# PURE. G3a: does this change of the SQL server's administrator need the proof? Action = none (not a move from one group
|       to another, or no database setup job at this install) | settled (the job identity has been a member of the new group
|       for -SettleHours) | verify (a run of the job must sign in through the new group, else the move is rolled back).
|       -MemberSince: when the job identity's membership of the new group began (its PIM assignment's start); $null = not
|       known. Returns @{ Action; Detail }. #>
|    param([AllowEmptyString()][string]$CurrentSid = '', [AllowEmptyString()][string]$CurrentKind = '', [Parameter(Mandatory)][string]$NewGroupId,
|          [bool]$JobExists = $false, $MemberSince = $null, [datetime]$NowUtc = [datetime]::UtcNow, [int]$SettleHours = 24)
|    $o = { param($a, $d) [pscustomobject]@{ Action = $a; Detail = $d } }
|    if (-not $CurrentSid -or $CurrentSid -eq $NewGroupId) { return (& $o 'none' 'not a move: the server''s administrator is the group already, or none') }
|    if ($CurrentKind -ne 'group') { return (& $o 'none' 'the server''s administrator today is not a group: the database setup job does not sign in through it') }
|    if (-not $JobExists) { return (& $o 'none' 'no database setup job at this install: nothing signs in through the old group') }
|    if ($MemberSince -is [datetime] -and ($NowUtc.ToUniversalTime() - $MemberSince.ToUniversalTime()).TotalHours -ge $SettleHours) {
|        return (& $o 'settled' ('the database setup job''s identity has been a member of the new group since {0:yyyy-MM-dd HH:mm}Z (at least {1} hours): its token carries it' -f $MemberSince.ToUniversalTime(), $SettleHours))
|    }
|    & $o 'verify' ('the database setup job''s identity is a member of the new group for less than {0} hours (or since a time not known): its token may still carry only the old group -- a run of the job must sign in through the new group, else the move is rolled back' -f $SettleHours)
|}
|
|function Test-SISqlAdminMoveSignIn {
|    <# G3a, after the move: the database setup job started (SI_DBINIT_BY installer) and waited for; it ends successfully only
|       when it signed in through the server's administrator group and read every identity back. A run that does not
|       succeed is started again after each -SettleWaits (the new membership reaching the token); none succeeds = Ok $false.
|       Returns @{ Ok; Execution; Tries; Detail }. Never throws. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup,
|          [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s }, [int[]]$SettleWaits = @(300, 600), [int]$TimeoutSeconds = 1500)
|    $n = Get-SIDbInitNames
|    $jobId = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.App/jobs/{2}' -f $SubscriptionId, $ResourceGroup, $n.Job
|    $tries = 0; $last = ''
|    try {
|        $job = & $Arm 'GET' ('{0}?api-version={1}' -f $jobId, $n.AppApi) $null
|        if (-not $job) { return [pscustomobject]@{ Ok = $false; Execution = ''; Tries = 0; Detail = ('the job {0} is not there' -f $n.Job) } }
|        $waits = @($SettleWaits | Where-Object { $_ -gt 0 })
|        while ($true) {
|            $tries++
|            $r = Start-SIDbInitRun -Arm $Arm -JobId $jobId -Job $job -By 'installer' -TimeoutSeconds $TimeoutSeconds -Sleep $Sleep
|            if ($r.Ok) { return [pscustomobject]@{ Ok = $true; Execution = $r.Execution; Tries = $tries; Detail = ('the job {0} signed in through the new group (execution {1}, run {2})' -f $n.Job, $r.Execution, $tries) } }
|            $last = '{0}: {1}' -f $(if ($r.Execution) { $r.Execution } else { '(not started)' }), $r.Status
|            if ($tries -gt $waits.Count) { break }
|            & $Sleep ([int]$waits[$tries - 1])
|        }
|        [pscustomobject]@{ Ok = $false; Execution = ''; Tries = $tries; Detail = ('the job {0} did not sign in through the new group in {1} run(s) (last {2})' -f $n.Job, $tries, $last) }
|    } catch { [pscustomobject]@{ Ok = $false; Execution = ''; Tries = $tries; Detail = ('the job {0} could not be run: {1}' -f $n.Job, $_.Exception.Message) } }
|}
|
|function Restore-SISqlAdminBlock {
|    <# G3a ROLLBACK: the server's administrators block (as read BEFORE the move: sid, login, kind, tenant, the Entra-only
|       setting) written back whole in one PATCH, then READ BACK until the server shows it. Returns @{ Ok; Detail }. Never throws. #>
|    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$ServerPath, [Parameter(Mandatory)]$Previous,
|          [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s }, [int]$Tries = 36, [int]$PollSeconds = 5)
|    try {
|        $api = (Get-SIDbInitNames).SqlApi
|        $block = [ordered]@{ administratorType = 'ActiveDirectory' }
|        foreach ($k in 'principalType', 'login', 'sid', 'tenantId', 'azureADOnlyAuthentication') {
|            $v = Get-SIDbInitProp $Previous @($k)
|            if ($null -ne $v -and "$v" -ne '') { $block[$k] = $v }
|        }
|        if (-not $block.Contains('sid')) { return [pscustomobject]@{ Ok = $false; Detail = 'the administrator before the move is not known -- nothing to put back' } }
|        $null = & $Arm 'PATCH' ('{0}?api-version={1}' -f $ServerPath, $api) ([ordered]@{ properties = [ordered]@{ administrators = $block } })
|        for ($i = 0; $i -lt $Tries; $i++) {
|            $s = $null; try { $s = & $Arm 'GET' ('{0}?api-version={1}' -f $ServerPath, $api) $null } catch { $s = $null }
|            $a = Get-SIDbInitProp $s @('properties', 'administrators')
|            if ($a -and [string](Get-SIDbInitProp $a @('sid')) -eq [string]$block.sid -and (-not $block.Contains('principalType') -or [string](Get-SIDbInitProp $a @('principalType')) -ieq [string]$block.principalType)) {
|                return [pscustomobject]@{ Ok = $true; Detail = ('the server''s administrator is {0} again (read back)' -f [string]$block.login) }
|            }
|            & $Sleep $PollSeconds
|        }
|        [pscustomobject]@{ Ok = $false; Detail = ('the server''s administrator was written back to {0}, but it does not read back yet -- check the server' -f [string]$block.login) }
|    } catch { [pscustomobject]@{ Ok = $false; Detail = ('putting the administrator back failed: {0}' -f $_.Exception.Message) } }
|}
'@ }
$__siSupportFiles['setup/_shared/SI-DisplayNames.ps1'] = @{ Sha256 = '3d9453e1cd61e090880ba81c12e455024851ccea07a0142ce9a3e509add9f8e6'; Text = @'
|#Requires -Version 5.1
|<#
|    SI-DisplayNames.ps1 -- THE NAMES PEOPLE READ, at EXISTING installs too (framework DOCS/REQUIREMENTS.md section 12.11c item 5,
|    SI REQUIREMENTS #655 item 5). Owner: "Short code in Azure, full name where people read"; existing installs: "if a resource
|    can be renamed, we do that. if not, we keep for now, display names are updated".
|
|    WHAT IS RENAMED (Get-SIDisplayNameRenames) -- directory objects only, and only from SecurityInsight's own earlier default:
|      the web app's sign-in application (app registration + enterprise application)  "SecurityInsight Management" -> "SecurityInsight"
|      SecurityInsight's engine application (app registration + enterprise application) "SecurityInsight" -> "SecurityInsight Engine"
|      the SQL admin group (display name only; mailNickname grpsisqladmins kept)        "grp-si-sql-admins" -> "SecurityInsight SQL admins"
|    NEVER renamed: an Azure resource (container app, job, managed identity, SQL server, Key Vault, registry -- Azure cannot), a
|    name the customer chose (anything but the earlier default is left exactly as it is), the mail sender's ADDRESS and the
|    Exchange scope (customers' mail rules). The mail sender's DISPLAY name has always been "SecurityInsight" (setup\Set-SIMail.ps1):
|    it is read and reported, never changed.
|
|    ORDER AND SAFETY
|      * the engine application FIRST: the web app's sign-in application takes the name "SecurityInsight", which the engine's
|        application carries today. While any OTHER application is still named "SecurityInsight" the sign-in application is HELD
|        (one line says which application) -- two applications of one name would let a lookup by name pick the wrong one.
|      * an object is identified by its id, never by its name: the sign-in application by the web app's client id
|        (AzureAd__ClientId), the engine's by its client id (SI_SPN_AppId), the group as the SQL server's Entra admin (its sid).
|      * each rename is read back; a rename that does not read back is PUT BACK to the earlier name, and an application whose
|        enterprise application could not follow is put back too -- never half-renamed.
|      * NEVER TWICE: an object renamed once is recorded (-Done: object id -> UTC); when someone named it back since, it is left.
|        The update renames only where it can keep that record (the Pro database); without it, it says what it would rename.
|      * THE UPDATE'S SWITCH SI_Update_RenameDisplayNames is ON by default (owner 2026-10-18: "everything that we can rename,
|        must follow agreed naming. consistent"); $false keeps the update to the plan.
|      * every FINDER that looked for the earlier name also finds the new one (Find-SISqlAdminGroup, Get-SIDisplayNameAliases,
|        the Graph finders in SI-GraphRest.ps1, New-SIManagementAppRegistration.ps1), so a setup run after the rename never
|        creates a second object -- and never names it back.
|
|    Pure except the -Graph seam: { param([string]$Method, [string]$Uri, $Body) } -> the parsed answer; throws on a failure.
|    ASCII only; PowerShell 5.1-safe.
|#>
|
|function Get-SIDisplayNameRenames {
|    <# PURE. Every directory object whose display name SecurityInsight renames at an existing install, in the order they are
|       renamed (the engine application before the sign-in application: see the header). #>
|    [ordered]@{
|        EngineApp     = [pscustomobject]@{ Role = 'EngineApp'; Kind = 'application'; Old = 'SecurityInsight'; New = 'SecurityInsight Engine'; Nick = ''
|                                           What = 'SecurityInsight''s engine application' }
|        WebSignInApp  = [pscustomobject]@{ Role = 'WebSignInApp'; Kind = 'application'; Old = 'SecurityInsight Management'; New = 'SecurityInsight'; Nick = ''
|                                           What = 'the web app''s sign-in application' }
|        SqlAdminGroup = [pscustomobject]@{ Role = 'SqlAdminGroup'; Kind = 'group'; Old = 'grp-si-sql-admins'; New = 'SecurityInsight SQL admins'; Nick = 'grpsisqladmins'
|                                           What = 'the SQL admin group' }
|    }
|}
|
|function Get-SIWebSignInRoleIds {
|    <# PURE. The stable app role ids of the web app's sign-in application (pro-management\deploy\New-SIManagementAppRegistration.ps1):
|       an application that carries one of them IS the sign-in application, whatever its name. #>
|    @('5f1e6c62-6a3b-4c38-9d8f-2a1d0c9e7a05', '5f1e6c62-6a3b-4c38-9d8f-2a1d0c9e7a01', '5f1e6c62-6a3b-4c38-9d8f-2a1d0c9e7a02',
|      '5f1e6c62-6a3b-4c38-9d8f-2a1d0c9e7a04', '5f1e6c62-6a3b-4c38-9d8f-2a1d0c9e7a06')
|}
|
|function Test-SIWebSignInApplication {
|    <# PURE. Does this application / service principal (an object with appRoles) carry one of the sign-in application's role ids? #>
|    param([AllowNull()]$Object)
|    if ($null -eq $Object -or -not $Object.PSObject.Properties['appRoles']) { return $false }
|    $ids = Get-SIWebSignInRoleIds
|    [bool]@(@($Object.appRoles) | Where-Object { $_ -and $_.PSObject.Properties['id'] -and $ids -contains [string]$_.id }).Count
|}
|
|function Get-SIDisplayNameAliases {
|    <# PURE. Every display name the object of -Role may carry, the name asked for first: today's earlier default and the new
|       one. -Name: the name a caller looks for (a customer's own name has no aliases: just itself). #>
|    param([Parameter(Mandatory)][ValidateSet('EngineApp', 'WebSignInApp', 'SqlAdminGroup')][string]$Role, [AllowEmptyString()][string]$Name = '')
|    $r = (Get-SIDisplayNameRenames)[$Role]
|    $n = "$Name".Trim()
|    if ($n -and $n -cne $r.Old -and $n -cne $r.New) { return @($n) }
|    if ($n -ceq $r.New) { return @($r.New, $r.Old) }
|    @($r.Old, $r.New)
|}
|
|function Test-SIDisplayNameRenameOn {
|    <#
|        PURE. Is SI_Update_RenameDisplayNames ON for this install? ON BY DEFAULT (owner 2026-10-18: "everything that we can
|        rename, must follow agreed naming. consistent" -- every existing install reaches the names a new install gets). Only
|        an explicit 'false' / '0' / 'no' / 'off' (a JSON value of the Pro database may carry quotes) turns it off; not set,
|        empty or anything else is on. From -Values (the install's Pro setting / config), else -Env (default: the process --
|        the updater job's variable). Off: the update says what it WOULD rename, one line each, and changes nothing;
|        setup\Set-SIDisplayNames.ps1 -Apply (an administrator) renames regardless.
|    #>
|    param([System.Collections.IDictionary]$Values, [System.Collections.IDictionary]$Env)
|    $name = 'SI_Update_RenameDisplayNames'
|    $v = $null
|    if ($Values -and $Values.Contains($name)) { $v = $Values[$name] }
|    if ($null -eq $v -or "$v".Trim() -eq '') { $v = if ($Env) { if ($Env.Contains($name)) { $Env[$name] } else { $null } } else { [Environment]::GetEnvironmentVariable($name) } }
|    if ($v -is [bool]) { return [bool]$v }
|    -not ("$v".Trim().Trim('"').Trim('$').Trim() -match '^(?i)(false|0|no|off)$')
|}
|
|function Get-SIDisplayNameSettingSql {
|    <# PURE. The Pro database's value of SI_Update_RenameDisplayNames (the web app's Settings page; solution scope): one
|       ValueJson, or no row (not set = the default, on). #>
|    "IF OBJECT_ID('cfg.Setting') IS NOT NULL SELECT ValueJson FROM cfg.Setting WHERE Name = N'SI_Update_RenameDisplayNames' AND Scope = N'solution';"
|}
|
|function Get-SIDisplayNameProp {
|    param([AllowNull()]$Object, [Parameter(Mandatory)][string]$Name)
|    if ($null -eq $Object) { return $null }
|    if ($Object -is [System.Collections.IDictionary]) { return $Object[$Name] }
|    if ($Object.PSObject.Properties[$Name]) { return $Object.$Name }
|    $null
|}
|
|function Get-SISqlAdminGroupFilter {
|    <# PURE. The Graph $filter that finds the SQL admin group -GroupName under ANY of its names: the name asked for, the other
|       of SecurityInsight's two display names, and its mailNickname (which never changes). A customer's own group: its name only. #>
|    param([AllowEmptyString()][string]$GroupName = 'grp-si-sql-admins')
|    # SI #750 (2026-10-27): a Community edition install's own group (setup\_shared\SI-SetupNaming.ps1, side by side with a Pro
|    # install in the same tenant) is found under ITS two names and its mailNickname -- never under the Pro group's names
|    $c = Get-SICommunitySqlAdminGroupNames
|    if ("$GroupName".Trim() -ceq $c.Old -or "$GroupName".Trim() -ceq $c.New) {
|        return (@(("displayName eq '{0}'" -f $c.Old), ("displayName eq '{0}'" -f $c.New), ("mailNickname eq '{0}'" -f $c.Nick)) -join ' or ')
|    }
|    $r = (Get-SIDisplayNameRenames)['SqlAdminGroup']
|    $names = @(Get-SIDisplayNameAliases -Role SqlAdminGroup -Name $GroupName)
|    $parts = @($names | ForEach-Object { "displayName eq '{0}'" -f $_.Replace("'", "''") })
|    if ($names -ccontains $r.Old) { $parts += ("mailNickname eq '{0}'" -f $r.Nick) }
|    $parts -join ' or '
|}
|
|function Get-SICommunitySqlAdminGroupNames {
|    <# PURE. The Community edition install's SQL admin group (SI #750, side by side with a Pro install in one tenant): the name it
|       is created and looked up by, the name people read, and its mailNickname (Set-SISqlAdminGroup.ps1: -GroupName without
|       its separators). Not renamed by the update: it has had its final display name from the start. #>
|    [pscustomobject]@{ Old = 'grp-si-community-sql-admins'; New = 'SecurityInsight Community SQL admins'; Nick = 'grpsicommunitysqladmins' }
|}
|
|function Find-SISqlAdminGroup {
|    <#
|        The SQL admin group by any of its names (Get-SISqlAdminGroupFilter), never by one display name only -- once renamed,
|        a lookup of "grp-si-sql-admins" alone would find nothing and a setup run would create a SECOND group. Returns
|        @{ Group (@{ Id; DisplayName; MailNickname; IsAssignableToRole; SecurityEnabled }, or $null); Count; Ids }.
|        More than one group: Group $null, Count > 1 (the caller refuses). Throws when the directory cannot be read.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [AllowEmptyString()][string]$GroupName = 'grp-si-sql-admins')
|    $f = [uri]::EscapeDataString((Get-SISqlAdminGroupFilter -GroupName $GroupName))
|    $r = & $Graph 'GET' ("https://graph.microsoft.com/v1.0/groups?`$filter=$f&`$select=id,displayName,mailNickname,securityEnabled,isAssignableToRole") $null
|    $seen = @{}; $list = New-Object System.Collections.Generic.List[object]
|    foreach ($g in @(Get-SIDisplayNameProp $r 'value')) {
|        if (-not $g) { continue }
|        $id = [string](Get-SIDisplayNameProp $g 'id'); if (-not $id -or $seen.ContainsKey($id)) { continue }
|        $seen[$id] = $true
|        $list.Add([pscustomobject]@{ Id = $id; DisplayName = [string](Get-SIDisplayNameProp $g 'displayName'); MailNickname = [string](Get-SIDisplayNameProp $g 'mailNickname')
|                                     IsAssignableToRole = [bool](Get-SIDisplayNameProp $g 'isAssignableToRole'); SecurityEnabled = [bool](Get-SIDisplayNameProp $g 'securityEnabled') })
|    }
|    [pscustomobject]@{ Group = $(if ($list.Count -eq 1) { $list[0] } else { $null }); Count = $list.Count; Ids = @($list | ForEach-Object { $_.Id }) }
|}
|
|function Get-SIDisplayNameErrorKind {
|    <# PURE. 'rights' when a failed Graph call was a refusal (403 / Authorization_RequestDenied / insufficient privileges), else 'error'. #>
|    param([AllowEmptyString()][string]$Text)
|    if ("$Text" -match '(?i)\b403\b|Authorization_RequestDenied|Insufficient privileges|Forbidden') { 'rights' } else { 'error' }
|}
|
|function Get-SIDisplayNameRightsText {
|    <# PURE. The rights a rename of -Kind needs, in one plain sentence. #>
|    param([Parameter(Mandatory)][ValidateSet('application', 'group')][string]$Kind)
|    if ($Kind -eq 'application') { return 'an owner of the application, or Application Administrator / Cloud Application Administrator (a person), or Microsoft Graph Application.ReadWrite.All (an app)' }
|    'Privileged Role Administrator (a person: the group is role-assignable), or Microsoft Graph Group.ReadWrite.All with RoleManagement.ReadWrite.Directory (an app)'
|}
|
|function Get-SIDisplayNamePlan {
|    <#
|        READ ONLY. What would be renamed at this install: one item per object SecurityInsight can identify --
|          @{ Role; Kind; What; Id (object id); AppId; SpId; SpName; Old; New; Current; Action; Line }
|        Action: rename | present (already the new name) | kept (a name of the customer's own, or named back after an earlier
|        rename -- never twice) | held (another application already carries the new name) | not-found | unchecked (could not
|        be read). -WebAppId / -EngineAppId: client ids ('' = not known, no item); -SqlAdminSid: the SQL server's Entra admin
|        ('' = no item). -Done: object id -> UTC of an earlier rename by SecurityInsight (the install's record).
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [AllowEmptyString()][string]$WebAppId = '', [AllowEmptyString()][string]$EngineAppId = '',
|          [AllowEmptyString()][string]$SqlAdminSid = '', [hashtable]$Done = @{})
|    $map = Get-SIDisplayNameRenames
|    $items = New-Object System.Collections.Generic.List[object]
|    $new = { param($r) [pscustomobject]@{ Role = $r.Role; Kind = $r.Kind; What = $r.What; Id = ''; AppId = ''; SpId = ''; SpName = ''; Old = $r.Old; New = $r.New; Current = ''; Action = ''; Line = '' } }
|    $decide = {
|        param($it)
|        if ($it.Current -ceq $it.New) { $it.Action = 'present'; $it.Line = ('{0} is already named "{1}"' -f $it.What, $it.New); return }
|        if ($it.Current -cne $it.Old) { $it.Action = 'kept'; $it.Line = ('{0} is named "{1}" (not SecurityInsight''s earlier name) -- kept as it is' -f $it.What, $it.Current); return }
|        if ($it.Id -and $Done.ContainsKey($it.Id)) { $it.Action = 'kept'; $it.Line = ('{0} was renamed to "{1}" on {2} and has been named "{3}" again since -- left as it is (never renamed twice)' -f $it.What, $it.New, $Done[$it.Id], $it.Old); return }
|        $it.Action = 'rename'; $it.Line = ('{0}: "{1}" -> "{2}"' -f $it.What, $it.Old, $it.New)
|    }
|    $readApp = {
|        param($r, [string]$appId)
|        $it = & $new $r; $it.AppId = $appId
|        try {
|            $a = & $Graph 'GET' ("https://graph.microsoft.com/v1.0/applications(appId='{0}')?`$select=id,appId,displayName" -f $appId) $null
|            if (-not $a -or -not [string](Get-SIDisplayNameProp $a 'id')) { $it.Action = 'not-found'; $it.Line = ('{0} (client id {1}) was not found -- nothing to rename' -f $it.What, $appId); return $it }
|            $it.Id = [string](Get-SIDisplayNameProp $a 'id'); $it.Current = [string](Get-SIDisplayNameProp $a 'displayName')
|            try {
|                $s = & $Graph 'GET' ("https://graph.microsoft.com/v1.0/servicePrincipals?`$filter=appId eq '{0}'&`$select=id,displayName" -f $appId) $null
|                $sp = @(Get-SIDisplayNameProp $s 'value' | Where-Object { $_ })[0]
|                if ($sp) { $it.SpId = [string](Get-SIDisplayNameProp $sp 'id'); $it.SpName = [string](Get-SIDisplayNameProp $sp 'displayName') }
|            } catch { }
|            & $decide $it
|        } catch {
|            $it.Action = 'unchecked'
|            $it.Line = ('{0} (client id {1}) could not be read ({2}) -- not renamed' -f $it.What, $appId, $(if ((Get-SIDisplayNameErrorKind $_.Exception.Message) -eq 'rights') { 'this identity may not read applications' } else { $_.Exception.Message }))
|        }
|        $it
|    }
|    $engine = $null
|    if ("$EngineAppId".Trim()) { $engine = & $readApp $map['EngineApp'] "$EngineAppId".Trim(); $items.Add($engine) }
|    if ("$WebAppId".Trim()) {
|        $web = & $readApp $map['WebSignInApp'] "$WebAppId".Trim()
|        if ($web.Action -eq 'rename') {
|            # another application already named "SecurityInsight" (not this one, not the engine's about to be renamed): HELD
|            try {
|                $f = [uri]::EscapeDataString(("displayName eq '{0}'" -f $web.New))
|                $same = @(Get-SIDisplayNameProp (& $Graph 'GET' ("https://graph.microsoft.com/v1.0/applications?`$filter=$f&`$select=id,appId,displayName") $null) 'value' | Where-Object { $_ })
|                $others = @($same | Where-Object { [string](Get-SIDisplayNameProp $_ 'appId') -ine $web.AppId -and -not ($engine -and $engine.Action -eq 'rename' -and [string](Get-SIDisplayNameProp $_ 'appId') -ieq $engine.AppId) })
|                if ($others.Count) {
|                    $web.Action = 'held'
|                    $web.Line = ('{0} is NOT renamed to "{1}": another application already has that name (client id {2}) -- rename that one first (setup\Set-SIDisplayNames.ps1 -EngineAppId <its client id>), or give it a name of your own' -f $web.What, $web.New, ((@($others | ForEach-Object { [string](Get-SIDisplayNameProp $_ 'appId') })) -join ', '))
|                }
|            } catch {
|                $web.Action = 'unchecked'; $web.Line = ('{0}: whether another application is already named "{1}" could not be read ({2}) -- not renamed' -f $web.What, $web.New, $_.Exception.Message)
|            }
|        }
|        $items.Add($web)
|    }
|    if ("$SqlAdminSid".Trim()) {
|        $r = $map['SqlAdminGroup']; $it = & $new $r
|        try {
|            $g = & $Graph 'GET' ("https://graph.microsoft.com/v1.0/groups/{0}?`$select=id,displayName,mailNickname" -f "$SqlAdminSid".Trim()) $null
|            if (-not $g -or -not [string](Get-SIDisplayNameProp $g 'id')) { $it.Action = 'not-found'; $it.Line = 'the SQL server''s Entra admin is not a group -- no admin group to rename' }
|            else {
|                $it.Id = [string](Get-SIDisplayNameProp $g 'id'); $it.Current = [string](Get-SIDisplayNameProp $g 'displayName')
|                $nick = [string](Get-SIDisplayNameProp $g 'mailNickname')
|                # only SecurityInsight's own group (its mailNickname, or one of its two names): a customer's own admin group is never touched
|                if ($nick -cne $r.Nick -and $it.Current -cne $r.Old -and $it.Current -cne $r.New) { $it.Action = 'kept'; $it.Line = ('the SQL server''s admin group is "{0}", a group of your own -- kept as it is' -f $it.Current) }
|                # framework §5.5 / §12.11c (Invardia, 2026-11-07): the SQL admin group's name is its STANDARD name
|                # grp-si-sql-admins, not a display name -- this step never renames it any more (it would undo the update's
|                # identity-names step, setup\_shared\SI-IdentityNamesStep.ps1, which renames it back in place with the SQL
|                # server's admin login)
|                elseif ($it.Current -ceq $r.Old) { $it.Action = 'present'; $it.Line = ('the SQL admin group has its standard name "{0}"' -f $r.Old) }
|                else { $it.Action = 'kept'; $it.Line = ('the SQL admin group is "{0}" -- the update''s identity-names step gives it its standard name "{1}" (not this step)' -f $it.Current, $r.Old) }
|            }
|        } catch {
|            # a 404 = the admin is not a group (a person, an application)
|            if ("$($_.Exception.Message)" -match '(?i)\b404\b|Request_ResourceNotFound|does not exist') { $it.Action = 'not-found'; $it.Line = 'the SQL server''s Entra admin is not a group -- no admin group to rename' }
|            else { $it.Action = 'unchecked'; $it.Line = ('the SQL admin group could not be read ({0}) -- not renamed' -f $(if ((Get-SIDisplayNameErrorKind $_.Exception.Message) -eq 'rights') { 'this identity may not read groups' } else { $_.Exception.Message })) }
|        }
|        $items.Add($it)
|    }
|    # one item per object, enumerated (callers wrap the call in @())
|    $items.ToArray()
|}
|
|function Set-SIDisplayNameOnObject {
|    <# One PATCH of displayName on -Path (applications/<id>, servicePrincipals/<id>, groups/<id>), then READ BACK (a few tries:
|       the directory replicates). $true = it reads back as -Name. Throws when the PATCH is refused. #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$Name, [scriptblock]$Sleep, [int[]]$Waits = @(0, 5, 10, 20))
|    $null = & $Graph 'PATCH' ("https://graph.microsoft.com/v1.0/{0}" -f $Path) (@{ displayName = $Name } | ConvertTo-Json -Compress)
|    foreach ($w in $Waits) {
|        if ($w) { if ($Sleep) { & $Sleep $w } else { Start-Sleep -Seconds $w } }
|        try { $b = & $Graph 'GET' ("https://graph.microsoft.com/v1.0/{0}?`$select=id,displayName" -f $Path) $null; if ([string](Get-SIDisplayNameProp $b 'displayName') -ceq $Name) { return $true } } catch { }
|    }
|    $false
|}
|
|function Invoke-SIDisplayNameRenames {
|    <#
|        THE RENAME, item by item (the plan of Get-SIDisplayNamePlan, in its order). Only items with Action 'rename', only with
|        -Apply. An application: the app registration, then its enterprise application (when it carries the earlier name); a
|        group: its display name (mailNickname never). Each change READ BACK; a change that does not read back -- or an
|        application whose enterprise application could not follow -- is PUT BACK to the earlier name and read back again.
|        A refusal names the rights it needs and the setup script that does it. Never throws.
|        Returns @{ Items (each + State: renamed | planned | failed | no-rights | put-back-failed, and Line); Lines; Done
|        (object id -> UTC for what was renamed now); Renamed (count) }.
|    #>
|    param([Parameter(Mandatory)][scriptblock]$Graph, [AllowEmptyCollection()][object[]]$Plan = @(), [switch]$Apply, [scriptblock]$Sleep,
|          [string]$SetupCommand = '.\setup\Set-SIDisplayNames.ps1 -Apply', [datetime]$NowUtc = [datetime]::UtcNow)
|    $lines = New-Object System.Collections.Generic.List[string]; $done = @{}; $n = 0
|    $stamp = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture)
|    $out = foreach ($it in @($Plan)) {
|        if (-not $it) { continue }
|        $o = [pscustomobject]@{ Role = $it.Role; Kind = $it.Kind; Id = $it.Id; Old = $it.Old; New = $it.New; Action = $it.Action; State = $it.Action; Line = $it.Line }
|        if ($it.Action -ne 'rename') { $o; continue }
|        if (-not $Apply) { $o.State = 'planned'; $o.Line = 'would rename ' + $it.Line; $lines.Add($o.Line); $o; continue }
|        $root = if ($it.Kind -eq 'application') { 'applications/' + $it.Id } else { 'groups/' + $it.Id }
|        $changed = @()
|        try {
|            if (-not (Set-SIDisplayNameOnObject -Graph $Graph -Path $root -Name $it.New -Sleep $Sleep)) { $changed += $root; throw 'it did not read back under the new name' }
|            $changed += $root
|            if ($it.Kind -eq 'application' -and $it.SpId -and $it.SpName -ceq $it.Old) {
|                $spPath = 'servicePrincipals/' + $it.SpId
|                if (-not (Set-SIDisplayNameOnObject -Graph $Graph -Path $spPath -Name $it.New -Sleep $Sleep)) { $changed += $spPath; throw 'its enterprise application did not read back under the new name' }
|                $changed += $spPath
|            }
|            $o.State = 'renamed'; $o.Line = 'renamed ' + $it.Line + ', read back'; $done[$it.Id] = $stamp; $n++
|        } catch {
|            $why = [string]$_.Exception.Message
|            $kind = Get-SIDisplayNameErrorKind $why
|            # PUT BACK: everything this item changed returns to the earlier name (never half-renamed)
|            $back = $true
|            foreach ($p in @($changed)) { try { if (-not (Set-SIDisplayNameOnObject -Graph $Graph -Path $p -Name $it.Old -Sleep $Sleep)) { $back = $false } } catch { $back = $false } }
|            if (-not $back) { $o.State = 'put-back-failed'; $o.Line = ('{0} could NOT be renamed ({1}) and could not be put back to "{2}" either -- check it in the Entra admin center' -f $it.What, $why, $it.Old) }
|            elseif ($kind -eq 'rights') { $o.State = 'no-rights'; $o.Line = ('{0} is NOT renamed: this identity may not change it. It needs {1}. An administrator renames it with: {2}' -f $it.What, (Get-SIDisplayNameRightsText -Kind $it.Kind), $SetupCommand) }
|            else { $o.State = 'failed'; $o.Line = ('{0} is NOT renamed ({1}){2}' -f $it.What, $why, $(if (@($changed).Count) { ' -- put back to "' + $it.Old + '"' } else { '' })) }
|        }
|        $lines.Add($o.Line)
|        $o
|    }
|    [pscustomobject]@{ Items = @($out); Lines = $lines.ToArray(); Done = $done; Renamed = $n }
|}
|
|function ConvertFrom-SIDisplayNamesRecord {
|    <# PURE. The record cfg.InstallState 'DisplayNames' (compact JSON: object id -> UTC) as a hashtable; empty when none / not JSON. #>
|    param([AllowNull()][AllowEmptyString()][string]$Value)
|    $h = @{}
|    if (-not "$Value".Trim()) { return $h }
|    try { $o = "$Value" | ConvertFrom-Json -ErrorAction Stop } catch { return $h }
|    # PowerShell 7's ConvertFrom-Json turns an ISO date string into a [datetime]: written back as the same UTC text
|    if ($o -is [System.Management.Automation.PSCustomObject]) {
|        foreach ($p in $o.PSObject.Properties) {
|            $val = if ($p.Value -is [datetime]) { $p.Value.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) } else { "$($p.Value)".Trim() }
|            if ($val) { $h[$p.Name] = $val }
|        }
|    }
|    $h
|}
|
|function Get-SIDisplayNamesRecordSql {
|    <# PURE. -Read: the stored record (one value or no row); else the upsert of @Value (the whole record) by @By. #>
|    param([switch]$Read)
|    if ($Read) { return "IF OBJECT_ID('cfg.InstallState') IS NOT NULL SELECT Value FROM cfg.InstallState WHERE Name = N'DisplayNames';" }
|    @'
|IF OBJECT_ID('cfg.InstallState') IS NOT NULL
|BEGIN
|    SET XACT_ABORT ON;
|    BEGIN TRAN;
|    IF EXISTS (SELECT 1 FROM cfg.InstallState WITH (UPDLOCK, HOLDLOCK) WHERE Name = N'DisplayNames')
|        UPDATE cfg.InstallState SET Value = @Value, UpdatedAt = SYSUTCDATETIME(), UpdatedBy = @By WHERE Name = N'DisplayNames';
|    ELSE
|        INSERT cfg.InstallState (Name, Value, [Version], UpdatedBy) VALUES (N'DisplayNames', @Value, NULL, @By);
|    COMMIT;
|END
|'@
|}
|
|function Merge-SIDisplayNamesRecord {
|    <# PURE. -Current (the record) with -Done (what was renamed now) added; an id renamed before keeps its first date. Compact JSON. #>
|    param([hashtable]$Current = @{}, [hashtable]$Done = @{})
|    $m = [ordered]@{}
|    foreach ($k in @($Current.Keys | Sort-Object)) { $m[$k] = $Current[$k] }
|    foreach ($k in @($Done.Keys | Sort-Object)) { if (-not $m.Contains($k)) { $m[$k] = $Done[$k] } }
|    $m | ConvertTo-Json -Compress
|}
'@ }

# ---- the runner (release/Build-SISupportScripts.ps1) ----------------------------------------------------------------
$__siSupportDir = [IO.Path]::Combine([IO.Path]::GetTempPath(), ('securityinsight-support-' + [guid]::NewGuid().ToString('N').Substring(0, 12)))
$__siSupportWritten = New-Object System.Collections.Generic.List[string]
$__siSupportSha = [System.Security.Cryptography.SHA256]::Create()
try {
    foreach ($__k in @($__siSupportFiles.Keys)) {
        $__lines = ($__siSupportFiles[$__k].Text -replace "`r", '') -split "`n"
        $__body = (@($__lines | ForEach-Object { if ($_.StartsWith('|')) { $_.Substring(1) } else { $_ } }) -join "`r`n") + "`r`n"
        $__hash = -join ($__siSupportSha.ComputeHash((New-Object System.Text.UTF8Encoding($false)).GetBytes($__body)) | ForEach-Object { $_.ToString('x2') })
        if ($__hash -ne $__siSupportFiles[$__k].Sha256) { throw "SecurityInsight standalone script: the embedded file '$__k' is damaged (SHA-256 mismatch) -- download the script again." }
        $__p = [IO.Path]::Combine($__siSupportDir, ($__k -replace '/', [string][IO.Path]::DirectorySeparatorChar))
        $__d = [IO.Path]::GetDirectoryName($__p)
        if (-not [IO.Directory]::Exists($__d)) { [void][IO.Directory]::CreateDirectory($__d) }
        [IO.File]::WriteAllText($__p, $__body, (New-Object System.Text.UTF8Encoding($__k -match '\.ps[dm]?1$')))
        $__siSupportWritten.Add($__p)
    }
    $__target = [IO.Path]::Combine($__siSupportDir, ($__siSupportEntry -replace '/', [string][IO.Path]::DirectorySeparatorChar))
    if ($env:SI_SUPPORT_SELFTEST -eq '1') {
        # the support pipeline's own check: every file extracted and verified, the entry script's parameters readable
        $__cmd = Get-Command -Name $__target -ErrorAction Stop
        [pscustomobject]@{ SISupportSelfTest = 'ok'; Version = $__siSupportVersion; Entry = $__siSupportEntry; Files = $__siSupportWritten.Count; Parameters = @($__cmd.Parameters.Keys) }
        return
    }
    $global:LASTEXITCODE = 0
    & $__target @PSBoundParameters
    $__exit = $LASTEXITCODE
} finally {
    $__siSupportSha.Dispose()
    foreach ($__p in $__siSupportWritten) { try { [IO.File]::Delete($__p) } catch { } }
    if ([IO.Directory]::Exists($__siSupportDir)) {
        $__left = @([IO.Directory]::GetFiles($__siSupportDir, '*', [IO.SearchOption]::AllDirectories))
        if ($__left.Count) { Write-Host ("SecurityInsight: the script left {0} file(s) (logs or output) in {1}" -f $__left.Count, $__siSupportDir) }
        else { try { [IO.Directory]::Delete($__siSupportDir, $true) } catch { } }
    }
}
if ($__exit) { exit $__exit }