#Requires -Version 7.0
# PIM Manager 3.0.70 -- Invoke-PimSupportSqlAccessJob.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: _pimscriptdoc.ps1, ..\..\engine\_shared\pim-rest.ps1, pim-loopbackanswer.ps1, _pimsignedin.ps1, _pimsupportsqlaccess.ps1, _pimsupportsqljob.ps1, ..\..\engine\_shared\pim-supportjit.ps1)


<#
.SYNOPSIS
  Gives the Invardia Support app its read-only database user on a PIM Manager installation whose database is private (public network access off), from inside: a one-time job in the installation's own environment runs the support access step (the user from the application's client id, in the read role pim_support_read only), the result is read back, and the job is removed. Nothing is opened; -WhatIf shows it first. With -SupportHours the database owner role is given for that many hours only (never above the level you consented to): the job stays, takes the role back at the end by itself, and the read-only access stays.

.DESCRIPTION
  PIM REQUIREMENTS 100.116 (framework 4.1b). On an installation with a public database, Grant-PimSupportSqlAccess.ps1
  does this from the machine it runs on. A PRIVATE database has no route from outside, and none is made for this: no
  firewall rule, no public access, no jump host. The grant runs inside the installation's own network instead, and
  you -- the customer -- start it.

  What it does, in order:
    1. Reads the installation's own database setup job (ca-pim-dbinit, else caj-pim-dbinit): its environment, its image, the SQL server and
       database it names, and the user-assigned identity it signs in to the database with. That identity is the SQL
       server's administrator (or a member of the SQL admin group); it is used as it is. No role, no group membership
       and no permission is given to any identity. When the installation has no such job or identity, the script
       STOPS, changes nothing, and prints the options.
    2. Reads whether a job of the one-time name is already there (a leftover of a killed run of this script is removed
       first; any other job of that name is not touched and stops the run), and that the Invardia Support app exists
       in this tenant.
    3. Creates the one-time job (caj-pim-supportsql) in the same environment, with that identity and a tag that says
       what it is.
    4. Starts it once. In the database, the job runs the support access step with the consent level (-ConsentLevel
       troubleshoot | setup; without it the level already recorded, else troubleshoot): the user from the Support app's
       client id when no user has that id (an existing user of the Support app is reused whatever its name), in
       pim_support_read only, then reads it back. It never adds the database owner role; one an earlier version gave
       is shown as a WARNING and left as found.
    5. Waits for the execution, reads its result and its log lines, and prints PASS or FAIL with them.
    6. ALWAYS, also after a failed step: removes the one-time job and reads back that it is gone.

  Time-limited access, in three steps:
    -InstallSupportAccess -ConsentLevel none|troubleshoot|setup  ONCE per installation (an owner-level step): records the level
        you consent to, gives the Support app's database user read-only access, and installs the signed procedures that
        give and take back the time-limited access. They take no user as a parameter: the Support app and your consent
        level are read from a table only a database owner can change.
    -SupportHours 1-8 [-Level setup|troubleshoot]  opens it: the level given is the LOWER of the level asked and the level you
        consented to; for the database owner role the end is recorded with the role. The job stays and takes the role
        back at the end by itself, then ends the Support app's open database sessions; the read-only access stays.
        Nothing is taken back before the end, and nothing else has to happen for the access to end. A role the Support
        app held before is never taken away.
    -CloseSupportAccess  ends every open time-limited access now.
  Every run of the job first takes back any time-limited access whose end has passed, and so do the background jobs of
  PIM Manager on their own schedule; each of them reports what it took back. When the access is opened, the script waits
  for the job's result (read from its log lines) and leaves the job running; the next run of this script removes it.

  The step the job runs is the one Grant-PimSupportSqlAccess.ps1 runs: the job's script is built from the same
  functions. No SQL admin group membership is given by this script.

  Admin rights: consent 'setup' lets a support session (-SupportHours, at most 8) add the database owner role until its
  end; consent 'troubleshoot' is read-only. Outside a session the Support app reads only.

  Sign-in: your own browser sign-in (or the Invardia Support app's session open in this window). No Azure CLI, no
  PowerShell module, no secret on the command line. Every token is pinned to -TenantId.

  Exit codes: 0 PASS (or a preview with nothing in the way); 1 FAIL -- the reason and the next step are printed.

.EXAMPLE
  .\Invoke-PimSupportSqlAccessJob.ps1 -TenantId <tenant id> -SubscriptionId <subscription id> -ResourceGroup rg-pim -SupportAppId <Invardia Support app client id> -WhatIf
  Preview: reads everything, prints what it would do and the script the job would run. Then the same command without -WhatIf.

.EXAMPLE
  .\Invoke-PimSupportSqlAccessJob.ps1 -TenantId <tenant id> -SubscriptionId <subscription id> -ResourceGroup rg-pim -SupportAppId <Invardia Support app client id> -SupportHours 8 -TicketNumber 12345 -Reason 'database repair'
  Time-limited: the database owner role for 8 hours, taken back by the job at the end.

.EXAMPLE
  .\Invoke-PimSupportSqlAccessJob.ps1 -TenantId <tenant id> -SubscriptionId <subscription id> -ResourceGroup rg-pim -SupportAppId <Invardia Support app client id> -InstallSupportAccess -ConsentLevel owner
  Once per installation: records the consent level and installs the time-limited support access.

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
    Role: Contributor (or Owner) on the resource group of the PIM Manager installation (Azure); Log Analytics Reader on
          the installation's Log Analytics workspace to show the job's log lines (optional).
    Hosts: login.microsoftonline.com, management.azure.com, graph.microsoft.com, api.loganalytics.io. Nothing to the
           SQL server from this computer: only the job, inside the installation's network, reaches the database.

    PERMISSIONS AND CHANGES (from Invoke-PimSupportSqlAccessJob.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Invoke-PimSupportSqlAccessJob/)
    The person running it needs:
      - Contributor (or Owner) [azureRbac, the resource group of the PIM Manager installation] -- Reads the installation's database setup job and its environment; creates, starts and deletes the one-time job; and assigns to that job the user-assigned identities the setup job already carries (the assign action on those identities is part of Contributor).
      - Log Analytics Reader [azureRbac, the Log Analytics workspace of the installation's Container Apps environment (optional)] -- Reads the job's log lines. Without it the verdict still comes from how the execution ended; the script then says the log could not be read.
      - Your own browser sign-in, or the Invardia Support app's session in this window [other, the target tenant and subscription] -- A session of another tenant than -TenantId, or of another application than -SupportAppId, is refused. No Azure CLI, no PowerShell modules, no secret on the command line.
    What it creates, changes or grants:
      - grant a database user for the Invardia Support app, created by the one-time job from the application's client id (CREATE USER ... WITH SID, never FROM EXTERNAL PROVIDER) when no user has that id; an existing user of the Support app is reused whatever its name; made by the support access step with the consent level (-ConsentLevel troubleshoot or setup, else the level already recorded, else troubleshoot) (The PIM database): pim_support_read (read-only: SELECT on the product schemas) @ the one PIM database the installation's database setup job names (PIM_SqlDatabase, default PimPlatform) -- Invardia support reads the store to troubleshoot. This is the Support app's only standing database right. The job never adds db_owner; one an earlier version gave is shown as a warning and left as found. Undo: Run Grant-PimSupportAccess.ps1 -Remove from inside the network (drops the user), or switch the Invardia Support app off in Microsoft Entra ID, which ends the access at once.
      - grant with -SupportHours: the level asked (-Level setup or troubleshoot), but never above the level the customer consented to (the lower of the two); for the database owner role the end is recorded with the role (one record per role added). At the end the job takes the database owner role back by itself, then ends the Support app's open database sessions, and ends; the read-only access stays. A role the Support app held before is never taken away. Every run of the job, and the background jobs of PIM Manager, take back any time-limited access whose end has passed (The PIM database): db_owner (database owner) until the end, at most 8 hours; pim_support_read (read-only: SELECT on the product schemas) stays @ the one PIM database the installation's database setup job names (PIM_SqlDatabase, default PimPlatform) -- Support gets the owner right only while it works on the installation; the access ends at the stated time without anyone having to remember it. Undo: None needed: the job takes the owner role back at the end. To end it sooner: -CloseSupportAccess, or switch the Invardia Support app off in Microsoft Entra ID, which ends the access at once.
      - create with -InstallSupportAccess -ConsentLevel: once per installation, the consent level the customer gives (none, troubleshoot or setup) for this Support app, in a table only a database owner can change; the read role pim_support_read (SELECT on the product schemas only) and the Support app's database user in it (an earlier membership of db_datareader is taken away once it is in that role: narrower, never wider) -- with none, no Support database user at all; three procedures that open, close and report the time-limited access and take no user as a parameter, signed by a certificate created in the database (its private key removed right after signing), with changes to them refused to everyone but the database owner (The PIM database) @ the one PIM database the installation's database setup job names -- So the time-limited access can be opened and closed by PIM Manager's own jobs without them being database owners, and only ever for the Support app at the level the customer chose. Undo: Run -InstallSupportAccess again with -ConsentLevel none: every open access is closed and the Support app's database user is removed.
      - grant with -InstallSupportAccess: the right to run the procedures that close the time-limited access and report it, for PIM Manager's engine and web app (so their regular jobs end an access that has passed its end), and the right to read the state for the updater; only the database job may run the one that opens it (The PIM database): EXECUTE on those procedures only @ the three support access procedures in the PIM database -- PIM Manager's own jobs close the time-limited access on their own schedule without being database owners. Undo: Run -InstallSupportAccess again with -ConsentLevel none: nothing can be opened any more.
      - update with -CloseSupportAccess: every open time-limited access is ended now (only the roles it added), then the Support app's open database sessions (The PIM database) @ the one PIM database the installation's database setup job names -- Support is finished before the end that was set. Undo: Open it again with -SupportHours.
      - create the one-time Container Apps job (default name caj-pim-supportsql, tag pim-one-time-job = support-sql-access) in the installation's own Container Apps environment, on the image of the database setup job, with the user-assigned identities that job already carries (the SQL admin identity and, when it differs, the image-pull identity). No role, no group membership and no permission is given to any identity. (Azure (the PIM resource group)) @ the resource group of the installation -- A private database has no route from outside; the job runs where the route already is. No firewall rule, no public access and no network path is opened. Undo: None needed: the run removes the job and reads back that it is gone, also after a failed step. If the run is killed: Azure portal > the resource group > caj-pim-supportsql > Delete, or run the script again (it removes a leftover that carries its tag first).
      - remove the one-time job this run created -- or a leftover of the same name that carries this script's tag. A job of that name without the tag is never touched. (Azure (the PIM resource group)) @ the resource group of the installation -- The job is for one run. It carries the SQL admin identity, so it is not left behind. Undo: None needed: the installation does not use this job.
    -WhatIf: Signs in, reads the database setup job, whether a job of the one-time name exists and that the Support app exists in the tenant, prints the database, the identity and the image it would use, and one 'What if:' line for each thing it would do: create the one-time job, start it once (take back any time-limited access whose end has passed; the read-only user from the client id in pim_support_read only -- with -SupportHours, db_owner until the end), read the result, remove the job (with -SupportHours: leave it running until it has taken the access back). It also prints the whole script the job would run. No job is created, nothing reaches the database. Nothing is changed.
    Undo: Run Grant-PimSupportAccess.ps1 -Remove from inside the network (drops the database user), or switch the Invardia Support app off in Microsoft Entra ID. The one-time job is removed by the run itself. With -SupportHours the owner role ends at the stated time by itself.

.LINK
    https://invardia.com/docs/pim/scripts/Invoke-PimSupportSqlAccessJob/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][ValidatePattern('^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')][string]$TenantId,
    [Parameter(Mandatory)][ValidatePattern('^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')][string]$SubscriptionId,
    # the resource group of the PIM Manager installation (its Container Apps environment and jobs)
    [Parameter(Mandatory)][ValidatePattern('^[A-Za-z0-9_.()-]{1,90}$')][string]$ResourceGroup,
    # the Invardia Support app's application (client) id. In the Support app's own session it may be left out.
    [ValidatePattern('^$|^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')][string]$SupportAppId = '',
    [string]$DbUserName = 'invardia-support',
    # the installation's own job the identity, the image and the database are read from
    [ValidatePattern('^[a-z][a-z0-9-]{0,30}[a-z0-9]$')][string]$TemplateJobName = 'ca-pim-dbinit',
    # the name of the one-time job (created, run once, removed)
    [ValidatePattern('^[a-z][a-z0-9-]{0,30}[a-z0-9]$')][string]$JobName = 'caj-pim-supportsql',
    # only when the template job does not name its database identity itself: the client id of a user-assigned identity it already carries
    [ValidatePattern('^$|^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')][string]$SqlIdentityClientId = '',
    [ValidateRange(60, 3600)][int]$TimeoutSeconds = 600,
    # time-limited access: the database owner role for this many hours (1-8), taken back by the job at the end; 0 = the standing access
    [ValidateRange(0, 8)][int]$SupportHours = 0,
    # with -SupportHours: the level asked (the level given is the lower of this and the consented level); v1 owner / read = setup / troubleshoot
    [ValidateSet('setup', 'troubleshoot', 'owner', 'read')][string]$Level = 'setup',
    # with -SupportHours: why the access is opened, and the support ticket it belongs to (recorded with the end)
    [ValidatePattern('^[A-Za-z0-9 ._@:#/()+,-]{0,120}$')][string]$Reason = '',
    [ValidatePattern('^[A-Za-z0-9._#-]{0,40}$')][string]$TicketNumber = '',
    # once per installation: record the consent level and install the time-limited support access
    [switch]$InstallSupportAccess,
    # with -InstallSupportAccess: none | troubleshoot | setup; without a step switch (the read-only user): troubleshoot | setup
    # ('' = the level already recorded, else troubleshoot)
    [ValidateSet('', 'none', 'troubleshoot', 'setup', 'read', 'owner')][string]$ConsentLevel = '',   # v1 read / owner = troubleshoot / setup
    # end every open time-limited support access now
    [switch]$CloseSupportAccess,
    # --- test seams (tests/Test-PimSupportSqlJob.ps1); omit them for a real run ---
    [scriptblock]$Arm,
    [scriptblock]$Graph,
    [scriptblock]$Logs,
    [scriptblock]$Sleep,
    [int]$PollSeconds = 10,
    [int]$LogWaitSeconds = 180
)
$ErrorActionPreference = 'Stop'
# Published as ONE standalone file (https://invardia.com/support/pim/Invoke-PimSupportSqlAccessJob.ps1): every helper is
# dot-sourced by a literal path relative to this script's folder, so Build-PimSupportScripts.ps1 inlines it.
# ===== BEGIN inlined helper: _PimScriptDoc.ps1 =====
<#
.SYNOPSIS
    Framework 12.7 SCRIPT-DOC-1 + 12.10 item 11 -- the ONE place that knows where a PIM script's documentation page,
    download and checksum list live, the command form every surface shows (line 1 download, line 2+ run -- owner
    2026-10-11), and the run
    frame every script a person runs uses (the first line "<Script> version <x.y.z> - documentation: <page>",
    REQUIREMENTS 100.52, and a local transcript).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# ===== END inlined helper: _PimScriptDoc.ps1 =====
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-Rest.ps1 =====
<#
  PIM4EntraPS -- pure-REST auth + data plane (NO Graph/Az/MSAL modules).

  One place the whole solution gets tokens and calls Microsoft REST APIs, so the
  engine runs identically on Windows PowerShell 5.1, PowerShell 7, a VM, or a Linux
  container -- with nothing to Install-Module and no Azure.Core/Graph version clash.

  Token acquisition (auto-detected, override per call):
    * Managed Identity  -- App Service / Container Apps ($env:IDENTITY_ENDPOINT + IDENTITY_HEADER), an Azure Arc-enabled
                           server (IDENTITY_ENDPOINT + IMDS_ENDPOINT, 401 key-file challenge) or IMDS (VM)
    * Client secret     -- SPN client_credentials (v2 token endpoint)
    * Client certificate-- SPN, signed RS256 JWT client_assertion (no secret, no MSAL)
    * Signed-in source  -- a registered $global:PIM_TokenProvider (tools\setup\_PimSignedIn.ps1): the Invardia
                           Support session, else the person's browser sign-in (auth code + PKCE). No CLI, no module.

  Resolution order for credentials (all overridable via params):
    explicit params -> $global:PIM_* -> Managed Identity -> the signed-in token source -> (opt-in) browser sign-in.

  Data plane: Invoke-PimGraph / -PimArm / -PimPowerBI / -PimRest with @odata/nextLink
  paging (-All) and 429/Retry-After backoff. PS 5.1 + 7 compatible (cert signing uses
  X509 GetRSAPrivateKey, NOT RSA.ImportFromPem which is PS7-only).
#>

Set-StrictMode -Off

# resource (audience) per logical API. Built by a FUNCTION so any scope can re-seed it --
# see the trap note in Resolve-PimRestResource: a dot-sourced function's $script: follows
# the CALLER's scope, so a script that loaded PIM-SqlStore without this file found these
# tables null and silently ended up with no SQL credential at all.
function Get-PimRestResourceMap {
  @{
    graph    = 'https://graph.microsoft.com'
    arm      = 'https://management.azure.com'
    powerbi  = 'https://analysis.windows.net/powerbi/api'
    fabric   = 'https://api.fabric.microsoft.com'     # PIM 100.142b: Fabric workspace role assignments (the engine adds the PIM group)
    defender = 'https://api.securitycenter.microsoft.com'
    exo      = 'https://outlook.office365.com'   # Exchange Online REST admin API (app-only ManageAsApp)
  }
}
$script:PimRestResources = Get-PimRestResourceMap
$script:PimTokenCache = @{}   # "audience|tenant|clientId|credentialKind" -> @{ token; expiresUtc }

function Clear-PimRestTokenCache {
    <#
      Drop every cached token. The cache is keyed by full identity (BUG-22), so this is
      NOT needed to switch tenants any more -- it exists for an explicit "forget
      everything" (a rotated credential mid-process, or a test).
    #>
    [CmdletBinding()] param()
    $script:PimTokenCache = @{}
}

function Add-PimRestSessionToken {
    <#
      97.1 -- hand a token the CALLER already holds (a setup script's browser sign-in: auth code + PKCE, no modules) to
      the token cache, so every Invoke-PimGraph / Invoke-PimArm / Invoke-PimRest / SQL call in THIS process uses it.
      Only for the attended interactive mode ($global:PIM_Interactive): the key is exactly the one Get-PimRestToken
      computes for that mode, so the engine's own identities (managed identity, certificate) can never pick it up.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$Resource, [Parameter(Mandatory)][string]$Token, [datetime]$ExpiresUtc = ((Get-Date).ToUniversalTime().AddMinutes(50)), [string]$TenantId)
    $aud = Resolve-PimRestResource -Resource $Resource
    $tenant = Get-PimTenantId -TenantId $TenantId
    $cid = if ($global:PIM_ClientId) { $global:PIM_ClientId } elseif ($env:AZURE_CLIENT_ID) { $env:AZURE_CLIENT_ID } else { $null }
    if (-not $script:PimTokenCache) { $script:PimTokenCache = @{} }
    $script:PimTokenCache[("$aud|$tenant|$cid|interactive").ToLowerInvariant()] = [pscustomobject]@{ token = $Token; expiresUtc = $ExpiresUtc.ToUniversalTime() }
}

function Resolve-PimRestResource {
  param([Parameter(Mandatory)][string]$Resource)
  # 🪤 $script: IS NOT A CLOSURE FOR A DOT-SOURCED FUNCTION. It binds to the script scope
  # the function is CALLED from, so when another script dot-sources PIM-SqlStore (or the
  # downlink) WITHOUT this file, these tables are $null there and `.ContainsKey()` throws
  # "You cannot call a method on a null-valued expression". New-PimSqlConnection catches
  # that, tries the next credential, and ends up presenting NO credential -- Azure SQL then
  # answers "Login failed for user ''", which sends everyone looking at permissions.
  # Re-seeding here makes the alias table work from any scope; the value is a constant map,
  # so there is nothing to lose by rebuilding it.
  if (-not $script:PimRestResources) { $script:PimRestResources = Get-PimRestResourceMap }
  if ($script:PimRestResources.ContainsKey($Resource)) { return $script:PimRestResources[$Resource] }
  return ($Resource -replace '/+$','')   # already a full audience URL
}

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

function Get-PimTenantId {
  param([string]$TenantId)
  if ($TenantId) { return $TenantId }
  if ($global:PIM_TenantId) { return $global:PIM_TenantId }
  if ($env:PIM_TenantId) { return $env:PIM_TenantId }
  if ($env:AZURE_TENANT_ID) { return $env:AZURE_TENANT_ID }
  return $null
}

# ---- Managed Identity (App Service / IMDS) --------------------------------
function ConvertTo-PimTokenExpiry {
  param($ExpiresOn)
  # App Service IDENTITY_ENDPOINT -> unix seconds; older MSI/some -> a date string.
  try { if ("$ExpiresOn" -match '^\d+$') { return ([datetimeoffset]::FromUnixTimeSeconds([int64]$ExpiresOn)).UtcDateTime } } catch {}
  try { return ([datetimeoffset]"$ExpiresOn").UtcDateTime } catch {}
  return (Get-Date).ToUniversalTime().AddMinutes(50)
}
function Set-PimManagedIdentityHomeTenant {
  # LIC anti-copy (2026-10-03): the tid claim of a MANAGED IDENTITY token = the tenant this environment really runs in.
  # Recorded once per process in $global:PIM_ManagedIdentityTenantId; PIM-License.ps1 checks the licence against it, so a
  # licence cannot be made valid elsewhere by editing PIM_TenantId. Never throws.
  param([string]$Token)
  try {
    $seg = "$Token".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($seg.Length % 4) { $seg += '=' }
    $tid = "$(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($seg)) | ConvertFrom-Json).tid)".Trim().ToLowerInvariant()
    if ($tid -match '^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$') { $global:PIM_ManagedIdentityTenantId = $tid }
  } catch { }
}
# ---- Azure Arc-enabled server (§100.63(b), the on-premises hybrid worker) ---------------------------------------------
# The Arc agent (himds) serves the machine's system-assigned identity on http://localhost:40342 and sets IDENTITY_ENDPOINT
# + IMDS_ENDPOINT machine-wide -- but NO IDENTITY_HEADER (that is App Service / Container Apps). Its token call is a
# CHALLENGE: the first GET answers 401 with `WWW-Authenticate: Basic realm=<path to a .key file>`; the caller proves it may
# use the identity by READING that file (only local Administrators and the local group "Hybrid agent extension
# applications" can) and retries with `Authorization: Basic <file content>`. The file is single-use and short-lived.
# 🔒 The realm is checked before anything is read: a .key file directly under %ProgramData%\AzureConnectedMachineAgent\Tokens,
# at most 4 KB -- an endpoint that names any other file is refused (else a rogue local listener could make us send it the
# content of an arbitrary file we can read).
$script:PimArcDefaultEndpoint = 'http://localhost:40342/metadata/identity/oauth2/token'
function Get-PimArcTokenDirectory {
  if ("$($global:PIM_ArcTokenDirectory)".Trim()) { return "$($global:PIM_ArcTokenDirectory)".Trim() }   # offline test seam
  $pd = if ("$env:ProgramData".Trim()) { $env:ProgramData } else { 'C:\ProgramData' }
  return (Join-Path $pd 'AzureConnectedMachineAgent\Tokens')
}
function Get-PimArcIdentityEndpoint {
  # '' = not an Arc host. Arc = IDENTITY_ENDPOINT + IMDS_ENDPOINT set and no IDENTITY_HEADER / MSI_SECRET, or (env not yet
  # visible to this process -- a service started before the agent was installed) the himds service is present.
  if ($global:PIM_ArcIdentityEndpoint) { return "$($global:PIM_ArcIdentityEndpoint)" }   # offline test seam
  if ("$env:IDENTITY_HEADER".Trim() -or "$env:MSI_SECRET".Trim()) { return '' }
  if ("$env:IDENTITY_ENDPOINT".Trim() -and "$env:IMDS_ENDPOINT".Trim()) { return "$env:IDENTITY_ENDPOINT".Trim() }
  if ($global:PIM_NoManagedIdentity -or $global:PIM_NoArcProbe) { return '' }
  if ($null -eq $script:PimArcHimdsPresent) {
    $script:PimArcHimdsPresent = $false
    if ("$env:OS" -eq 'Windows_NT') { try { $script:PimArcHimdsPresent = [bool](Get-Service -Name 'himds' -ErrorAction Stop) } catch { $script:PimArcHimdsPresent = $false } }
  }
  if ($script:PimArcHimdsPresent) { return $script:PimArcDefaultEndpoint }
  return ''
}
function Test-PimArcKeyFilePath {
  # PURE. Is this realm path a file the Arc agent would hand out? Directly under the token directory, *.key, no traversal.
  param([AllowEmptyString()][string]$Path, [Parameter(Mandatory)][string]$TokenDirectory)
  $p = "$Path".Trim().Trim('"')
  if (-not $p -or $p -match '\.\.' -or $p -notmatch '(?i)\.key$') { return $false }
  $full = $null; $dir = $null
  try { $full = [IO.Path]::GetFullPath($p); $dir = [IO.Path]::GetFullPath($TokenDirectory).TrimEnd('\', '/') } catch { $full = $null }
  if (-not $full -or -not $dir) { return $false }
  return ([IO.Path]::GetDirectoryName($full).TrimEnd('\', '/') -ieq $dir)
}
function Invoke-PimArcIdentityHttp {
  # ONE GET against the local Arc endpoint that never throws on an HTTP status: returns status, WWW-Authenticate, body.
  # No proxy (on-premises servers often have a system proxy; localhost must never go through it). Seam: PIM_ArcIdentityHttpStub.
  param([Parameter(Mandatory)][string]$Uri, [hashtable]$Headers = @{}, [int]$TimeoutSec = 30)
  if ($global:PIM_ArcIdentityHttpStub -is [scriptblock]) { return (& $global:PIM_ArcIdentityHttpStub $Uri $Headers) }
  $req = [System.Net.HttpWebRequest][System.Net.WebRequest]::Create($Uri)
  $req.Method = 'GET'; $req.Proxy = $null; $req.Timeout = $TimeoutSec * 1000; $req.ReadWriteTimeout = $TimeoutSec * 1000
  foreach ($k in $Headers.Keys) { $req.Headers[$k] = "$($Headers[$k])" }
  $resp = $null
  try { $resp = $req.GetResponse() }
  catch [System.Net.WebException] { $resp = $_.Exception.Response; if (-not $resp) { throw } }
  catch { if ($_.Exception.InnerException -is [System.Net.WebException] -and $_.Exception.InnerException.Response) { $resp = $_.Exception.InnerException.Response } else { throw } }
  $out = $null
  try {
    $sr = New-Object System.IO.StreamReader($resp.GetResponseStream())
    $body = $sr.ReadToEnd(); $sr.Close()
    $out = [pscustomobject]@{ status = [int]$resp.StatusCode; wwwAuthenticate = "$($resp.Headers['WWW-Authenticate'])"; body = $body }
  } finally { $resp.Close() }
  return $out
}
function Get-PimArcManagedIdentityToken {
  param([Parameter(Mandatory)][string]$Audience, [string]$Endpoint = '')
  $ep = if ("$Endpoint".Trim()) { "$Endpoint".Trim() } else { Get-PimArcIdentityEndpoint }
  if (-not $ep) { throw 'not an Azure Arc-enabled server (no IDENTITY_ENDPOINT/IMDS_ENDPOINT and no himds service)' }
  $u = "$($ep)?resource=$([uri]::EscapeDataString($Audience))&api-version=2020-06-01"
  $first = Invoke-PimArcIdentityHttp -Uri $u -Headers @{ Metadata = 'true' }
  $r = $first
  if ($first.status -eq 401) {
    $m = [regex]::Match("$($first.wwwAuthenticate)", '(?i)Basic\s+realm\s*=\s*"?([^"]+?)"?\s*$')
    if (-not $m.Success) { throw "Arc identity endpoint answered 401 without a Basic realm (WWW-Authenticate: '$($first.wwwAuthenticate)')" }
    $keyPath = $m.Groups[1].Value
    $dir = Get-PimArcTokenDirectory
    if (-not (Test-PimArcKeyFilePath -Path $keyPath -TokenDirectory $dir)) { throw "Arc identity endpoint named a key file outside '$dir' ('$keyPath') -- refusing to read it" }
    $len = -1; try { $len = (New-Object IO.FileInfo($keyPath)).Length } catch { $len = -1 }
    if ($len -gt 4096) { throw "Arc key file '$keyPath' is $len bytes (more than 4 KB) -- refusing" }
    $secret = $null; $readErr = $null
    try { $secret = [IO.File]::ReadAllText($keyPath).Trim() } catch { $readErr = $_.Exception }
    if ($readErr -is [System.UnauthorizedAccessException] -or ($readErr -and $readErr.InnerException -is [System.UnauthorizedAccessException])) {
      throw "cannot read the Arc key file '$keyPath' as $([Security.Principal.WindowsIdentity]::GetCurrent().Name) -- add this account to the local group 'Hybrid agent extension applications' (or run as a local administrator), then start a new process"
    }
    if ($readErr) { throw "cannot read the Arc key file '$keyPath': $($readErr.Message)" }
    if (-not $secret) { throw "the Arc key file '$keyPath' is empty" }
    $r = Invoke-PimArcIdentityHttp -Uri $u -Headers @{ Metadata = 'true'; Authorization = "Basic $secret" }
    $secret = $null
  }
  if ($r.status -ne 200) { throw "Arc identity endpoint answered HTTP $($r.status) for $Audience : $("$($r.body)".Substring(0, [Math]::Min(300, "$($r.body)".Length)))" }
  $j = "$($r.body)" | ConvertFrom-Json
  if (-not "$($j.access_token)") { throw "Arc identity endpoint returned no access_token for $Audience" }
  return [pscustomobject]@{ token = "$($j.access_token)"; expiresUtc = (ConvertTo-PimTokenExpiry $j.expires_on) }
}

function Test-PimMiTokenRetryable {
  <# PURE. MI-TOKEN-TRANSIENT: is a failed identity-endpoint call worth another try? No HTTP status (a timeout or a
     connection fault), 429 or 5xx = yes; any other status (400 identity not found, 401, 403, 404) = no. #>
  param([AllowNull()][object]$StatusCode)
  if ($null -eq $StatusCode -or "$StatusCode" -eq '' -or [int]$StatusCode -eq 0) { return $true }
  $s = [int]$StatusCode
  return ($s -eq 429 -or ($s -ge 500 -and $s -le 599))
}

function Get-PimManagedIdentityToken {
  param([Parameter(Mandatory)][string]$Audience)
  $res = [uri]::EscapeDataString($Audience)
  # App Service / Functions (current): IDENTITY_ENDPOINT + IDENTITY_HEADER (api 2019-08-01)
  if ($env:IDENTITY_ENDPOINT -and $env:IDENTITY_HEADER) {
    $u = "$($env:IDENTITY_ENDPOINT)?resource=$res&api-version=2019-08-01"
    # 🔴 BUG-76 -- THIS BRANCH IGNORED THE CONFIGURED MI CLIENT ID, AND THE IMDS BRANCH BELOW DOES
    # NOT. That asymmetry is the whole defect: with a USER-ASSIGNED-ONLY identity there is nothing
    # for the endpoint to default to, so no token is issued and the caller ends up presenting no
    # credential at all. Azure SQL then answers "Login failed for user '<token-identified
    # principal>'", which reads as a missing database user -- and it is not.
    # MEASURED on the greenfield slave 2026-08-27: ca-pim-tick carries `SystemAssigned,
    # UserAssigned` and logs "[mi] token via IDENTITY_ENDPOINT" happily, while ca-pim-downlink-s6
    # carries UserAssigned ALONE and logs that line NOT AT ALL -- the absence was the clue. Its
    # engine apply failed every run on `Preflight FAILED: ... no SELECT 1`, which sent the search
    # to contained users and grants (where a user was duly created, and changed nothing).
    # Container Apps is exactly the host that attaches a user-assigned identity on its own.
    $miCid = if ($global:PIM_ManagedIdentityClientId) { "$($global:PIM_ManagedIdentityClientId)".Trim() }
             elseif ($env:PIM_ManagedIdentityClientId) { "$($env:PIM_ManagedIdentityClientId)".Trim() } else { '' }
    if ($miCid) { $u += "&client_id=$([uri]::EscapeDataString($miCid))" }
    # MI-TOKEN-TRANSIENT (SUP-2026-00323, internal rfa-sync 2026-10-27 02:16Z): ONE GET, no retry, so a single fault of the
    # endpoint failed the whole run while every other token of that window was issued. Retry a timeout / connection fault /
    # 429 / 5xx after a short wait; a 4xx (e.g. 400 "identity not found") is an answer, not a fault, and is thrown at once.
    # MANAGER-REFRESH-DEGRADES-CACHE (2026-10-27): on internal the endpoint was out for ~7 s twice in one day (02:16Z,
    # 20:00Z), longer than 2 s + 5 s -- a third try after 15 s covers that (22 s in all).
    $delays = if ($null -ne $global:PIM_MiTokenRetryDelaysSec) { @($global:PIM_MiTokenRetryDelaysSec) } else { @(2, 5, 15) }
    $r = $null
    for ($try = 0; ; $try++) {
      try { $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ 'X-IDENTITY-HEADER' = $env:IDENTITY_HEADER } -TimeoutSec 60; break }
      catch {
        $st = $null; try { if ($_.Exception.Response) { $st = [int]$_.Exception.Response.StatusCode } } catch {}
        if ($try -ge $delays.Count -or -not (Test-PimMiTokenRetryable -StatusCode $st)) {
          throw "the identity endpoint did not issue a token after $($try + 1) attempt(s): $($_.Exception.Message)"
        }
        try { [System.Console]::Out.WriteLine("  [mi] identity endpoint attempt $($try + 1) failed ($(if ($st) { "HTTP $st" } else { 'no answer' })) -- retrying in $($delays[$try]) s") } catch {}
        Start-Sleep -Seconds ([int]$delays[$try])
      }
    }
    # §100.46: in the tick this is a start-up diagnostic (printed with the start-up block: on change / first of the day / PIM_LOG_VERBOSE=1)
    if ("$($r.access_token)") { $__mil = "  [mi] token via IDENTITY_ENDPOINT (len $($r.access_token.Length))"; if ($global:PIM_LogQuiet -and (Get-Command Write-PimStartupLine -ErrorAction SilentlyContinue)) { Write-PimStartupLine -Message $__mil } else { try { [System.Console]::Out.WriteLine($__mil) } catch {} } }  # Console.Out (not Write-Host): headless-safe from any scope (App Service has no console buffer; Write-Host throws there even from module scope)
    Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
  }
  # App Service (older / some Linux SKUs): MSI_ENDPOINT + MSI_SECRET (api 2017-09-01, header 'Secret')
  if ($env:MSI_ENDPOINT -and $env:MSI_SECRET) {
    $u = "$($env:MSI_ENDPOINT)?resource=$res&api-version=2017-09-01"
    $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ 'Secret' = $env:MSI_SECRET } -TimeoutSec 60
    if ("$($r.access_token)") { try { [System.Console]::Out.WriteLine("  [mi] token via MSI_ENDPOINT (len $($r.access_token.Length))") } catch {} }  # Console.Out: headless-safe from any scope
    Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
  }
  # Azure Arc-enabled server (on-premises hybrid worker, §100.63(b)): IDENTITY_ENDPOINT without IDENTITY_HEADER, 401 challenge
  if (Get-PimArcIdentityEndpoint) {
    $a = Get-PimArcManagedIdentityToken -Audience $Audience
    try { [System.Console]::Out.WriteLine("  [mi] token via the Azure Arc agent (len $($a.token.Length))") } catch {}
    Set-PimManagedIdentityHomeTenant -Token "$($a.token)"; return $a
  }
  # IMDS (Azure VM)
  $u = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$res"
  if ($global:PIM_ManagedIdentityClientId) { $u += "&client_id=$($global:PIM_ManagedIdentityClientId)" }
  $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ Metadata = 'true' } -TimeoutSec 5
  Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
}

# ---- SPN client secret ----------------------------------------------------
function Get-PimClientSecretToken {
  param([Parameter(Mandatory)][string]$TenantId,[Parameter(Mandatory)][string]$ClientId,[Parameter(Mandatory)][string]$ClientSecret,[Parameter(Mandatory)][string]$Audience)
  $body = @{ grant_type='client_credentials'; client_id=$ClientId; client_secret=$ClientSecret; scope="$Audience/.default" }
  $r = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body $body -TimeoutSec 60
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

# ---- SPN certificate (signed JWT assertion) -------------------------------
function Get-PimClientCertToken {
  param([Parameter(Mandatory)][string]$TenantId,[Parameter(Mandatory)][string]$ClientId,[Parameter(Mandatory)][System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate,[Parameter(Mandatory)][string]$Audience)
  $tokenUrl = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
  $now = [DateTimeOffset]::UtcNow
  $x5t = ConvertTo-PimBase64Url -Bytes $Certificate.GetCertHash()   # SHA1 thumbprint bytes
  $header = @{ alg='RS256'; typ='JWT'; x5t=$x5t } | ConvertTo-Json -Compress
  $claims = @{ aud=$tokenUrl; iss=$ClientId; sub=$ClientId; jti=([guid]::NewGuid().ToString())
              nbf=$now.ToUnixTimeSeconds(); exp=$now.AddMinutes(10).ToUnixTimeSeconds() } | ConvertTo-Json -Compress
  $h = ConvertTo-PimBase64Url -Bytes ([Text.Encoding]::UTF8.GetBytes($header))
  $c = ConvertTo-PimBase64Url -Bytes ([Text.Encoding]::UTF8.GetBytes($claims))
  $unsigned = "$h.$c"
  $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($Certificate)
  if (-not $rsa) { throw "Certificate has no usable RSA private key for JWT signing." }
  $sigBytes = $rsa.SignData([Text.Encoding]::UTF8.GetBytes($unsigned), [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
  $jwt = "$unsigned." + (ConvertTo-PimBase64Url -Bytes $sigBytes)
  $body = @{ grant_type='client_credentials'; client_id=$ClientId; scope="$Audience/.default"
            client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer'; client_assertion=$jwt }
  $r = Invoke-RestMethod -Method POST -Uri $tokenUrl -ContentType 'application/x-www-form-urlencoded' -Body $body -TimeoutSec 60
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

function Get-PimTokenTenantId {
    <#
      SEC-12 -- read the tenant a JWT actually belongs to, from its own claims.

      🔑 ASKING FOR A TENANT IS NOT THE SAME AS BEING GIVEN ONE, and until this existed there was
      no way to tell the difference: a token for the wrong directory is a perfectly valid string
      that succeeds at the call site and fails somewhere else as a permissions error. One
      `Split('.')[1]` turns that into a fact.

      PURE: no network, no validation of the signature (that is the resource's job) -- this only
      reads what the token SAYS about itself, which is exactly what is needed to catch "you asked
      for A and something handed you B". Returns the lowercased `tid`, or '' when the string is
      not a readable JWT -- never throws, because a caller reaching for a sanity check must not be
      broken BY the sanity check.
    #>
    [CmdletBinding()] param([string]$Token)
    try {
        $parts = "$Token".Split('.')
        if ($parts.Count -lt 2) { return '' }
        $p = $parts[1].Replace('-', '+').Replace('_', '/')
        while ($p.Length % 4) { $p += '=' }
        $claims = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json
        return "$($claims.tid)".Trim().ToLowerInvariant()
    } catch { return '' }
}

function Get-PimTokenAppId {
    <# SEC-12 companion: the appid a JWT claims. Same contract as Get-PimTokenTenantId. #>
    [CmdletBinding()] param([string]$Token)
    try {
        $parts = "$Token".Split('.')
        if ($parts.Count -lt 2) { return '' }
        $p = $parts[1].Replace('-', '+').Replace('_', '/')
        while ($p.Length % 4) { $p += '=' }
        $claims = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json
        return "$($claims.appid)".Trim().ToLowerInvariant()
    } catch { return '' }
}

function Resolve-PimCertificate {
  param([string]$Thumbprint)
  $tp = if ($Thumbprint) { $Thumbprint } elseif ($global:PIM_CertThumbprint) { $global:PIM_CertThumbprint } else { $null }
  if (-not $tp) { return $null }
  $tp = ($tp -replace '\s','').ToUpperInvariant()
  foreach ($store in @('Cert:\CurrentUser\My','Cert:\LocalMachine\My')) {
    $c = Get-ChildItem $store -ErrorAction SilentlyContinue | Where-Object { $_.Thumbprint -eq $tp } | Select-Object -First 1
    if ($c) { return $c }
  }
  return $null
}

# ---- interactive (delegated) -- BREAK-GLASS / emergency on a client PC ----
# Dependency-free auth-code + PKCE loopback. No MSAL, no Graph/Az modules.
# Used when there is no MI and no SPN credential (a cloud-only admin PC running
# the emergency edition): the operator signs in as THEMSELVES, so the resulting
# SQL/Graph/ARM action is audited under the human identity, not a shared app.
# Returns a raw access token for $Audience. Edge is launched explicitly to avoid
# the system-default-browser state-mismatch bug; any first-party public client
# accepts an arbitrary localhost redirect port.
function Get-PimInteractiveClientId {
  <# PURE. The first-party public client for a browser sign-in to -Audience: Graph -> the Microsoft Graph CLI client
     (pre-authorised for Graph only); everything else (ARM, Azure SQL, Key Vault, Storage) -> the Microsoft Azure CLI
     client APP ID (an app registration id used over REST, not the az program). AADSTS650057 on ARM, 2026-10-10. #>
  param([string]$Audience)
  # ONE client for every audience (2026-10-10, a customer's install stalled on a hidden SECOND sign-in window when Graph
  # used a different client): the Azure CLI first-party public client is pre-authorised for Graph AND ARM / SQL / Key
  # Vault / Storage in every tenant, so ONE browser sign-in serves all of them through its refresh token.
  return '04b07795-8ddb-461a-bbee-02f9e1bf7b46'
}

# REQ 100.76 (2026-10-11, a new customer's hosting step: "Login failed for user '<token-identified principal>'"): a signed-in
# build hands its step processes the person's REFRESH token(s) for the target tenant in $env:PIM_HANDOFF_REFRESH
# ({ "<tenant>|<public client id>": "<refresh token>" }, that process's environment only), instead of a pre-minted Azure SQL
# ACCESS token. The step creates the SQL server, sets its Entra admin and adds the person to the SQL admin group AFTER the
# build minted, so only a token minted at connect time carries that right. Entries for another tenant are never taken.
function Import-PimHandoffRefresh {
  param([string]$TenantId, [string]$Json = "$env:PIM_HANDOFF_REFRESH")
  if (-not "$Json".Trim()) { return 0 }
  if (-not ($global:PimInteractiveRefresh -is [hashtable])) { $global:PimInteractiveRefresh = @{} }
  $want = "$TenantId".Trim().ToLowerInvariant(); $n = 0
  try { $o = "$Json" | ConvertFrom-Json } catch { Write-Verbose "PIM_HANDOFF_REFRESH unreadable: $($_.Exception.Message)"; return 0 }
  foreach ($p in @($o.PSObject.Properties)) {
    $k = "$($p.Name)".Trim().ToLowerInvariant(); $v = "$($p.Value)".Trim()
    if (-not $v -or $k -notmatch '^[^|]+\|[^|]+$') { continue }
    if ($want -and $k.Split('|')[0] -ne $want) { continue }
    if (-not $global:PimInteractiveRefresh.ContainsKey($k)) { $global:PimInteractiveRefresh[$k] = $v; $n++ }
  }
  return $n
}

# REQ 100.76: the refresh tokens a signed-in build hands a step for -TenantId, as the JSON for $env:PIM_HANDOFF_REFRESH
# ('' when there are none). Pure over -Map (default: this process's in-memory refresh map).
function Get-PimHandoffRefreshJson {
  param([Parameter(Mandatory)][string]$TenantId, [object]$Map = $global:PimInteractiveRefresh)
  if (-not ($Map -is [hashtable]) -or -not $Map.Count) { return '' }
  $want = "$TenantId".Trim().ToLowerInvariant(); $out = [ordered]@{}
  foreach ($k in @($Map.Keys)) { $kl = "$k".ToLowerInvariant(); if ($kl.Split('|')[0] -eq $want -and "$($Map[$k])".Trim()) { $out[$kl] = "$($Map[$k])" } }
  if (-not $out.Count) { return '' }
  return ($out | ConvertTo-Json -Compress)
}

function New-PimLoopbackListeners {
  # The browser sign-in's redirect listeners: the IPv4 loopback on a free port AND the IPv6 loopback on the SAME port when
  # the machine has IPv6 (a "localhost" redirect may resolve to either). Loopback only. A port the IPv6 side cannot take
  # is retried on a new one (a few times); no IPv6 at all = the IPv4 listener alone, as before.
  for ($try = 0; $try -lt 5; $try++) {
    $v4 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
    $v4.Start()
    if (-not [System.Net.Sockets.Socket]::OSSupportsIPv6) { return $v4 }
    $p = ([System.Net.IPEndPoint]$v4.LocalEndpoint).Port
    try {
      $v6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, $p)
      $v6.Start()
      return @($v4, $v6)   # the caller wraps it in @(): one flat list
    } catch { $v4.Stop() }
  }
  $only = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0); $only.Start()
  return $only
}

function Get-PimInteractiveToken {
  param([Parameter(Mandatory)][string]$Audience,[string]$TenantId,[string]$ClientId,
        # section 9 account sign-in clarity: force a brand-new credential prompt (prompt=login)
        # instead of reusing a cached account. -ExpectedAccount, if the cached account
        # differs, also forces a fresh prompt so a stale account is never used silently.
        [switch]$ForceFreshAccount,[string]$ExpectedAccount,
        # REQ 100.76: only the silent refresh-token exchange -- $null instead of a browser window when there is none.
        [switch]$RefreshOnly)
  $tenant = if ($TenantId) { $TenantId } elseif (Get-PimTenantId) { Get-PimTenantId } else { 'organizations' }
  # Default public client PER AUDIENCE (2026-10-10, a customer's managed install failed with AADSTS650057 "Invalid
  # resource" for ARM): the Microsoft Graph CLI client (14d82eec-...) is pre-authorised for GRAPH only. Azure Resource
  # Manager, Azure SQL, Key Vault and Storage use the Microsoft Azure CLI first-party public client APP ID
  # (04b07795-..., an app registration id used over REST -- not the az program), pre-authorised for those in every tenant.
  $cid = if ($ClientId) { $ClientId } elseif ($global:PIM_InteractiveClientId) { $global:PIM_InteractiveClientId } else { Get-PimInteractiveClientId -Audience $Audience }

  # ONE sign-in: a refresh token from an earlier browser sign-in (same tenant + client) is exchanged for this audience --
  # no second window. Falls through to the browser only when there is none or the exchange is refused.
  if (-not $global:PimInteractiveRefresh) { $global:PimInteractiveRefresh = @{} }
  $rtKey = "$tenant|$cid".ToLowerInvariant()
  if (-not $global:PimInteractiveRefresh.ContainsKey($rtKey)) { [void](Import-PimHandoffRefresh -TenantId $tenant) }
  if ($global:PimInteractiveRefresh.ContainsKey($rtKey) -and -not $ForceFreshAccount) {
    try {
      $rr = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $cid; grant_type = 'refresh_token'; refresh_token = $global:PimInteractiveRefresh[$rtKey]
        scope = "$Audience/.default offline_access openid profile" }
      if ($rr.refresh_token) { $global:PimInteractiveRefresh[$rtKey] = $rr.refresh_token }
      if ($rr.access_token) { return [pscustomobject]@{ token = $rr.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$rr.expires_in - 60) } }
    } catch { Write-Verbose "refresh-token exchange for $Audience refused: $($_.Exception.Message) -- browser sign-in" }
  }
  if ($RefreshOnly) { return $null }

  $bytes = New-Object byte[] 32
  [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
  $verifier  = ConvertTo-PimBase64Url -Bytes $bytes
  $sha       = [System.Security.Cryptography.SHA256]::Create()
  $challenge = ConvertTo-PimBase64Url -Bytes ($sha.ComputeHash([System.Text.Encoding]::ASCII.GetBytes($verifier)))
  $state     = [guid]::NewGuid().ToString('N')

  # The redirect says "localhost" (what Entra's public clients accept on any port), and a browser may resolve it to the IPv4
  # OR the IPv6 loopback: listen on BOTH, on the same port (a customer 2026-10-21: an IPv4-only listener, the jump host's browser
  # went to [::1] -> "localhost refused to connect"). Loopback only -- never another interface.
  $tcps = @(New-PimLoopbackListeners)
  $port     = ([System.Net.IPEndPoint]$tcps[0].LocalEndpoint).Port
  $redirect = "http://localhost:$port/"

  # section 9 prompt clarity: select_account (always show the picker so a stale cached account
  # is never reused silently) unless a fresh sign-in is forced -> login. ConvertTo-
  # PimAuthCodePrompt is in PIM-AuthDiagnostics; fall back if it isn't dot-sourced.
  if (Get-Command ConvertTo-PimAuthCodePrompt -ErrorAction SilentlyContinue) {
    $prompt = ConvertTo-PimAuthCodePrompt -ForceFresh:$ForceFreshAccount -KnownStaleAccount $ExpectedAccount
  } else { $prompt = if ($ForceFreshAccount) { 'login' } else { 'select_account' } }

  $scope   = "$Audience/.default offline_access openid profile"
  $authUrl = "https://login.microsoftonline.com/$tenant/oauth2/v2.0/authorize" +
             "?client_id=$cid&response_type=code&response_mode=query" +
             "&redirect_uri=$([uri]::EscapeDataString($redirect))" +
             "&scope=$([uri]::EscapeDataString($scope))&state=$state" +
             "&code_challenge=$challenge&code_challenge_method=S256&prompt=$prompt"
  if ("$ExpectedAccount".Trim()) { $authUrl += "&login_hint=$([uri]::EscapeDataString($ExpectedAccount.Trim()))" }

  $edge = @(
    (Join-Path ${env:ProgramFiles(x86)} 'Microsoft\Edge\Application\msedge.exe'),
    (Join-Path $env:ProgramFiles 'Microsoft\Edge\Application\msedge.exe')
  ) | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1
  Write-Host "  [interactive] sign-in required for $Audience (loopback $redirect)" -ForegroundColor Yellow
  # 2026-10-10: tell the installer's progress feed BEFORE a browser window opens (a hidden window waited silently and the
  # customer saw "nothing happening"); the installer registers $global:PIM_SignInNotify.
  if ($global:PIM_SignInNotify -is [scriptblock]) { try { & $global:PIM_SignInNotify $Audience $tenant } catch { } }
  # A person whose browser opens in the wrong profile can paste the address into the right one (2026-10-10).
  Write-Host "  If the browser opens in the wrong profile or account, open this address in the browser profile of an admin of tenant ${tenant}:" -ForegroundColor Yellow
  Write-Host "  $authUrl" -ForegroundColor DarkGray
  # 2026-10-10 (a customer's install): a normal Edge window opens the DEFAULT profile, whose saved account signs in silently
  # -- the person never got a credential prompt and landed in the wrong tenant. An InPrivate window has no saved account,
  # so the sign-in form always appears. PIM_SIGNIN_BROWSER=none: open nothing, the person pastes the address above.
  $mode = "$env:PIM_SIGNIN_BROWSER".Trim().ToLowerInvariant()
  if ($mode -eq 'none') { Write-Host '  (PIM_SIGNIN_BROWSER=none: no browser opened -- paste the address above into the right browser)' -ForegroundColor Yellow }
  elseif ($edge) { Start-Process -FilePath $edge -ArgumentList @('--inprivate', '--new-window', $authUrl) -WhatIf:$false }
  else { Start-Process $authUrl -WhatIf:$false }   # fall back to default browser if Edge absent

  $query = $null
  try {
    # SIGNIN-PAGE (owner 2026-10-31, Invardia's Wait-AuthCode fix): only the answer (code / error) ends the wait, every
    # request gets a page, and the page keeps answering 10 s after it (engine/_shared/PIM-LoopbackAnswer.ps1).
    if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: PIM-LoopbackAnswer.ps1 =====
# PIM-LoopbackAnswer.ps1 -- the ONE wait for a browser sign-in's answer on the localhost loopback (auth code + PKCE).
# Used by every PIM browser sign-in: the REST library's own (signed-in setup scripts), the mail setup (Initialize-PimMailSender,
# Set-PimSmtpRelayPassword, Set-PimSqlTier), the engine-permissions grant and the Activator deploy scripts. The tools load the
# identical copy in tools\setup (they may not load engine files). Build-PimSupportScripts inlines it into each published script.
#
# Owner 2026-10-30/31 ("people are reporting this error" -- "This site can't be reached"; "yes fix the sign-in page in all
# scripts"), the same fix as Invardia's Wait-AuthCode: the old loops took the FIRST request -- often the browser's preload
# of the address or its icon request -- and a request that never sent a line held the loop, and once the answer came the
# listener stopped at once, so the browser's real load or a reload got "This site can't be reached". Now:
#   1. only a request whose query carries code= or error= is the answer; the loop goes on until one comes;
#   2. EVERY request gets a page (waiting / signed in / failed), never a closed connection;
#   3. after the answer the listener keeps answering for -GraceSeconds (10), so a second load shows "Signed in" too;
#   4. it throws only when no answer came within -Seconds.
# A connection that sends nothing (a speculative preconnect) is dropped after -ReadTimeoutMs and never blocks the loop.

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

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

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

# ===== END inlined helper: PIM-LoopbackAnswer.ps1 =====
    }
    $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 min) waiting for the sign-in to come back to this window -- nothing was changed. Run the same command again and finish the sign-in within 5 minutes.'
  } finally { foreach ($t in $tcps) { try { $t.Stop() } catch { } } }

  $kv = @{}
  foreach ($pair in ($query -split '&')) { $k,$v = $pair -split '=',2; $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+',' ')) } else { '' } }
  if ($kv['error'])            { throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])" }
  if ($kv['state'] -ne $state) { throw 'State mismatch on the loopback redirect -- close ALL browser windows and retry.' }
  if (-not $kv['code'])        { throw 'Sign-in redirect carried no authorization code.' }

  $r = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
    client_id     = $cid
    grant_type    = 'authorization_code'
    code          = $kv['code']
    redirect_uri  = $redirect
    code_verifier = $verifier
    scope         = $scope
  }
  # The account must belong to the TARGET tenant: a token from another tenant (wrong browser profile / account) stops here,
  # before any call is made with it.
  if ($tenant -match '^[0-9a-fA-F-]{36}$') {
    $tid = ''
    try {
      $pp = "$($r.access_token)".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($pp.Length % 4) { $pp += '=' }
      $tid = "$(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($pp)) | ConvertFrom-Json).tid)".Trim()
    } catch { $tid = '' }
    if ($tid -and $tid -ne $tenant) { throw "You signed in to tenant $tid, but this is for tenant $tenant -- sign in with an account of $tenant (use that admin's browser profile)." }
  }
  if ($r.refresh_token) { $global:PimInteractiveRefresh["$tenant|$cid".ToLowerInvariant()] = $r.refresh_token }   # in memory only, never written
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

# ---- framework 8.13 INSTALL-HANDOFF: one sign-in across Invardia's bootstrap and the product installer ----
# Invardia's bootstrap (Install-Invardia) signs the person in ONCE (browser PKCE, or the Cloud Shell user token) and, in
# the SAME process, just before it calls Install-PimManager, sets $env:PIM_HANDOFF_TOKENS =
#   { "https://management.azure.com/": { "access_token": "...", "expires_on": <epoch seconds> }, "https://graph.microsoft.com/": {...},
#     "https://database.windows.net/": {...} }
# ACCESS tokens only (no refresh token crosses the boundary); an audience it could not get is simply absent; it removes
# the variable in a finally block. Install-PimManager reads it ONCE (Import-PimHandoffTokens), clears it, and keeps only
# the tokens that pass the checks below in $global:PimHandoffTokens -- memory only, never a file, log, transcript or event.
# Every check is on the token's OWN claims (claims read only: this is our own process boundary, and the resource still
# validates the signature on every call).
#   tid       == the installation's tenant (config.tenantId). A mismatch on ANY audience refuses the WHOLE handoff: the
#                bootstrap signed in to a different tenant than the answers name, so none of it is trusted.
#   a USER    the token must be DELEGATED: Entra puts 'scp' only in delegated (user) tokens and 'roles' only (no scp) in
#                application tokens; 'idtyp' is an OPTIONAL claim, so 'idtyp = app' refuses but its absence proves nothing.
#                Rule: idtyp is not 'app' AND scp is present AND oid is a GUID. ('roles' beside scp is allowed: a user can
#                hold app roles.)
#   expiry    the earlier of expires_on and the JWT's exp must be more than 5 minutes away.
# A token failing a check (other than the tenant) is refused for ITS audience only; that audience falls back to PIM's own
# browser sign-in (Get-PimInteractiveToken, pinned to the tenant) when it is first needed, and that sign-in's in-memory
# refresh token then covers the other audiences PIM needs later.

function Get-PimHandoffAudienceKey {
  # PURE. The comparison key of an audience: 'https://management.azure.com/' and 'https://management.azure.com' are one.
  param([string]$Audience)
  return "$Audience".Trim().TrimEnd('/').ToLowerInvariant()
}

function ConvertFrom-PimHandoffJwt {
  # PURE. The payload claims of a JWT, or $null for anything that is not one. Never throws; never returns the token.
  param([string]$Token)
  try {
    $parts = "$Token".Split('.')
    if ($parts.Count -ne 3 -or -not $parts[1]) { return $null }
    $p = $parts[1].Replace('-', '+').Replace('_', '/')
    while ($p.Length % 4) { $p += '=' }
    $c = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json -ErrorAction Stop
    if ($null -eq $c -or $c -is [string] -or $c -is [ValueType]) { return $null }
    return $c
  } catch { return $null }
}

function ConvertTo-PimHandoffExpiry {
  # PURE. expires_on as a bootstrap hands it over -- epoch seconds (number or digit string: the MSAL / managed-identity /
  # Cloud Shell shape) or a date -- as a UTC [datetime], or $null when it cannot be read.
  param($Value)
  if ($null -eq $Value) { return $null }
  if ($Value -is [datetime]) { return $Value.ToUniversalTime() }
  if ($Value -is [DateTimeOffset]) { return $Value.UtcDateTime }
  $s = "$Value".Trim()
  if (-not $s) { return $null }
  if ($s -match '^\d{9,11}(\.\d+)?$') { try { return [DateTimeOffset]::FromUnixTimeSeconds([long][math]::Floor([double]$s)).UtcDateTime } catch { return $null } }
  $d = [DateTimeOffset]::MinValue
  if ([DateTimeOffset]::TryParse($s, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AssumeUniversal, [ref]$d)) { return $d.UtcDateTime }
  return $null
}

function Test-PimHandoffToken {
  <#
    PURE given -NowUtc. Check ONE handed-over access token (see the block above). Returns
    @{ ok; tenantMismatch; reason; expiresUtc; userName }. The reason never contains token text.
  #>
  param([string]$Token, $ExpiresOn, [Parameter(Mandatory)][string]$TenantId, [datetime]$NowUtc = [datetime]::UtcNow, [int]$MinValidityMinutes = 5,
        # APP-IDENTITY INSTALL (owner via Invardia 2026-10-21, Install-Invardia -ViaSupportApp): an APPLICATION token is
        # accepted ONLY when its appid is exactly this app -- the Invardia Support app of the session open in this process.
        # Empty (the default) = the user rule below, unchanged.
        [string]$AllowedAppId = '')
  $no = { param($why, [bool]$mismatch = $false) @{ ok = $false; tenantMismatch = $mismatch; reason = $why; expiresUtc = $null; userName = ''; kind = '' } }
  if (-not "$Token".Trim()) { return (& $no 'no access token was handed over') }
  $c = ConvertFrom-PimHandoffJwt -Token $Token
  if (-not $c) { return (& $no 'it is not a readable access token') }
  $want = "$TenantId".Trim().ToLowerInvariant()
  $tid = "$($c.tid)".Trim().ToLowerInvariant()
  if (-not $tid) { return (& $no 'it names no tenant (no tid claim)') }
  if ($tid -ne $want) { return (& $no "it is for tenant $tid, not this installation's tenant $want" $true) }
  $idtyp = "$($c.idtyp)".Trim().ToLowerInvariant()
  $kind = 'user'
  if ($idtyp -eq 'app' -or -not "$($c.scp)".Trim()) {
    $appid = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
    if (-not "$AllowedAppId".Trim() -or $appid -ne "$AllowedAppId".Trim().ToLowerInvariant()) { return (& $no 'it is an application token, not a signed-in user''s (idtyp=app or no delegated scp claim)') }
    $kind = 'app'
  }
  if ("$($c.oid)".Trim() -notmatch '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$') { return (& $no $(if ($kind -eq 'app') { 'it carries no object id (oid) of the application' } else { 'it carries no user object id (oid)' })) }
  $given = ConvertTo-PimHandoffExpiry -Value $ExpiresOn
  $jwtExp = $null
  if ("$($c.exp)".Trim() -match '^\d+$') { try { $jwtExp = [DateTimeOffset]::FromUnixTimeSeconds([long]"$($c.exp)".Trim()).UtcDateTime } catch { $jwtExp = $null } }
  $eff = @(@($given, $jwtExp) | Where-Object { $_ } | Sort-Object) | Select-Object -First 1
  if (-not $eff) { return (& $no 'it carries no expiry (no expires_on and no exp claim)') }
  if ($eff -le $NowUtc.ToUniversalTime().AddMinutes($MinValidityMinutes)) {
    return (& $no ("it expires at {0:yyyy-MM-dd HH:mm} UTC -- less than {1} minutes left" -f $eff, $MinValidityMinutes))
  }
  $upn = if ($kind -eq 'app') { '' } else { "$(if ($c.upn) { $c.upn } elseif ($c.unique_name) { $c.unique_name } elseif ($c.preferred_username) { $c.preferred_username } else { '' })".Trim() }
  return @{ ok = $true; tenantMismatch = $false; reason = ''; expiresUtc = $eff; userName = $upn; kind = $kind }
}

function Import-PimHandoffTokens {
  <#
    PURE given -NowUtc. Read the bootstrap's PIM_HANDOFF_TOKENS JSON and check every audience against -TenantId.
    Returns @{ present; refused; reason; accepted = @{ <audience key> = @{ token; expiresUtc } }; fallback = @(@{ audience; reason }) }.
      refused = a token for ANOTHER tenant was handed over: NOTHING is accepted (reason names the audience and both tenants).
      fallback = audiences that were handed over but refused (each falls back to the browser sign-in when it is needed).
    The values in 'accepted' are the only place the tokens go; the caller keeps them in memory and never prints them.
  #>
  param([string]$Json, [Parameter(Mandatory)][string]$TenantId, [datetime]$NowUtc = [datetime]::UtcNow,
        # APP-IDENTITY INSTALL: the Invardia Support app of the session open in this process ('' = users only, as before)
        [string]$AllowedAppId = '')
  $out = @{ present = $false; refused = $false; reason = ''; accepted = @{}; fallback = @(); kind = '' }
  if (-not "$Json".Trim()) { return $out }
  $out.present = $true
  $o = $null
  try { $o = $Json | ConvertFrom-Json -ErrorAction Stop } catch { $o = $null }
  if ($null -eq $o -or $o -is [string] -or $o -is [ValueType] -or $o -is [System.Array]) {
    $out.fallback = @(@{ audience = '(all)'; reason = 'the handed-over sign-in could not be read (not a JSON object)' })
    return $out
  }
  $mismatch = @()
  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 = "$($v.access_token)"; if ($v.PSObject.Properties['expires_on']) { $exp = $v.expires_on } }
    $t = Test-PimHandoffToken -Token $tok -ExpiresOn $exp -TenantId $TenantId -NowUtc $NowUtc -AllowedAppId $AllowedAppId
    if ($t.tenantMismatch) { $mismatch += "$($p.Name): $($t.reason)" }
    elseif ($t.ok) { $out.accepted[(Get-PimHandoffAudienceKey $p.Name)] = @{ token = $tok; expiresUtc = $t.expiresUtc; userName = $t.userName; kind = $t.kind } }
    else { $out.fallback += @{ audience = "$($p.Name)"; reason = $t.reason } }
    $tok = $null
  }
  # One principal per handoff: a person's tokens beside an application's would make "who did this" a guess -- refused whole.
  $kinds = @($out.accepted.Values | ForEach-Object { "$($_.kind)" } | Select-Object -Unique)
  if ($kinds.Count -gt 1) {
    $out.refused = $true; $out.accepted = @{}
    $out.reason = 'the sign-in handed over by Invardia''s installer is REFUSED as a whole -- it mixes a person''s tokens with an application''s; nothing from it is used.'
    return $out
  }
  $out.kind = "$(@($kinds)[0])"
  if ($mismatch.Count) {
    $out.refused = $true
    $out.accepted = @{}
    $out.reason = ('the sign-in handed over by Invardia''s installer is REFUSED as a whole -- ' + ($mismatch -join '; ') +
                   '. It signed in to a different tenant than the installation answers name; nothing from it is used.')
  }
  return $out
}

function Get-PimHandoffToken {
  <# The validated handed-over access token for -Audience in -TenantId ($global:PimHandoffTokens, memory only), or '' when
     there is none, it is for another tenant, or it has under 2 minutes left (then the normal sign-in answers). #>
  param([string]$Audience, [string]$TenantId)
  $h = $global:PimHandoffTokens
  if (-not ($h -is [hashtable]) -or -not ($h.tokens -is [hashtable]) -or -not $h.tokens.Count) { return '' }
  if (-not "$TenantId".Trim() -or "$($h.tenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return '' }
  $e = $h.tokens[(Get-PimHandoffAudienceKey $Audience)]
  if (-not $e -or -not "$($e.token)".Trim()) { return '' }
  if ($e.expiresUtc -le [datetime]::UtcNow.AddMinutes(2)) { return '' }
  return "$($e.token)"
}

# ---- the one entry point: get a token for a resource ----------------------
function Get-PimRestToken {
  [CmdletBinding()]
  param(
    [string]$Resource = 'graph',
    [string]$TenantId,[string]$ClientId,[string]$ClientSecret,
    [System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate,[string]$CertThumbprint,
    [switch]$UseManagedIdentity,[switch]$Interactive,[switch]$Force
  )
  $aud = Resolve-PimRestResource -Resource $Resource

  # The identity is resolved BEFORE the cache is consulted, because it is part of the
  # cache key. See BUG-22 below -- this ordering is the fix, do not move the lookup back
  # above these lines.
  $tenant = Get-PimTenantId -TenantId $TenantId
  $cid    = if ($ClientId) { $ClientId } elseif ($global:PIM_ClientId) { $global:PIM_ClientId } elseif ($env:AZURE_CLIENT_ID) { $env:AZURE_CLIENT_ID } else { $null }
  $sec    = if ($ClientSecret) { $ClientSecret } elseif ($global:PIM_ClientSecret) { $global:PIM_ClientSecret } elseif ($env:AZURE_CLIENT_SECRET) { $env:AZURE_CLIENT_SECRET } else { $null }
  # Cert thumbprint: explicit -CertThumbprint, else the engine SPN global / env. This is
  # the engine's real app-only auth (SPN + certificate, no secret) -- e.g. the
  # PIM4EntraPS-Engine cert in LocalMachine\My / CurrentUser\My.
  $thumb  = if ($CertThumbprint) { $CertThumbprint } elseif ($global:PIM_CertThumbprint) { $global:PIM_CertThumbprint } elseif ($env:PIM_CERT_THUMBPRINT) { $env:PIM_CERT_THUMBPRINT } else { $null }
  $cert   = if ($Certificate) { $Certificate } else { Resolve-PimCertificate -Thumbprint $thumb }

  # 🔴 SEC-12 -- WHAT THE CALLER ASKED FOR, which is NOT the same as what resolution produced.
  # Deliberately keyed on $thumb (the thumbprint that was REQUESTED), never on $cert (the object
  # that was RESOLVED): a certificate that was named and could not be loaded is a FAILURE TO
  # HONOUR the request, not the absence of one. Reading $cert here is exactly how a missing cert
  # became "no explicit identity was asked for" and slid onto the (since removed) ambient command-line fallback.
  $explicitIdentity = [bool]("$tenant".Trim()) -and [bool]("$cid".Trim()) -and
                      ([bool]("$sec".Trim()) -or [bool]("$thumb".Trim()) -or [bool]$Certificate)

  # BUG-22 (2026-08-06): this cache was keyed by the AUDIENCE ALONE -- no tenant, no client
  # id. In any process that touches TWO tenants, the second one silently reused the first
  # one's token, so every call meant for tenant B went to tenant A. That is precisely the
  # MSP master->slave fanout this product exists to run, and the failure is invisible: the
  # calls SUCCEED, against the wrong directory.
  #
  # Proven live: an S6 (local-slave) run targeting a tenant with ZERO PIM groups reported
  # "Groups live=85" -- the MASTER's group count -- and the verifier then found all six
  # groups missing from the managed tenant it was supposed to be managing. A write-shaped run would
  # have applied the customer's desired state to the MSP's own tenant.
  #
  # The key is now the full identity: audience + tenant + client + credential KIND (and the
  # cert thumbprint, so rotating a cert re-mints rather than serving the old token). No
  # secret material goes into the key.
  $mode = if ($Interactive -or $global:PIM_Interactive) { 'interactive' }
          elseif ($UseManagedIdentity -or $global:PIM_UseManagedIdentity -or ($env:IDENTITY_ENDPOINT -and -not $cid)) { 'mi' }
          elseif ($sec) { 'secret' }
          elseif ($cert) { "cert:$thumb" }
          elseif ($global:PIM_TokenProvider -is [scriptblock]) { 'signed-in' }
          else { 'unknown' }
  $key = ("$aud|$tenant|$cid|$mode").ToLowerInvariant()
  # same cross-scope guard as Resolve-PimRestResource: an unseeded cache must mean "cache
  # miss", never a thrown method call that the caller reads as "authentication failed".
  if (-not $script:PimTokenCache) { $script:PimTokenCache = @{} }
  if (-not $Force -and $script:PimTokenCache.ContainsKey($key)) {
    $e = $script:PimTokenCache[$key]
    if ($e.expiresUtc -gt (Get-Date).ToUniversalTime().AddMinutes(2)) { return $e.token }
  }

  # Framework 8.13 INSTALL-HANDOFF (REQ 100.66): the sign-in Invardia's bootstrap handed this process, already validated by
  # Import-PimHandoffTokens (this tenant, a USER, >5 min left) and held in memory only, answers FIRST for its audiences --
  # but never for a caller that named an explicit identity, and never for an explicit browser request (-Interactive, which
  # may need scopes the handed-over token does not carry). An audience it does not cover falls through to the sign-in below.
  # 🔴 2026-10-11 (a managed-tenant install, live): NEVER for Azure SQL. The handed-over database token is minted by the bootstrap
  # BEFORE this run creates the SQL server and makes the signed-in admin (or its group) the server's Entra admin -- that token
  # carries no such membership, and the schema step failed "Login failed for user '<token-identified principal>'". The
  # database audience always comes from a sign-in made now (after the assignment).
  if (-not $explicitIdentity -and -not ($Interactive -or $global:PIM_Interactive) -and "$aud" -notmatch '(?i)database\.windows\.net') {
    $hk = Get-PimHandoffToken -Audience $aud -TenantId $tenant
    if ($hk) { return $hk }
  }

  $res = $null
  # Explicit interactive request (break-glass): sign in as the human up front.
  if ($Interactive -or $global:PIM_Interactive) {
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant } catch { Write-Verbose "PIM-Rest interactive auth failed for ${Resource}: $($_.Exception.Message)" }
  }
  $primaryErr = $null
  if (-not $res) {
    try {
      if ($UseManagedIdentity -or $global:PIM_UseManagedIdentity -or ($env:IDENTITY_ENDPOINT -and -not $cid)) {
        $res = Get-PimManagedIdentityToken -Audience $aud
      }
      elseif ($tenant -and $cid -and $sec) {
        $res = Get-PimClientSecretToken -TenantId $tenant -ClientId $cid -ClientSecret $sec -Audience $aud
      }
      elseif ($tenant -and $cid -and $cert) {
        $res = Get-PimClientCertToken -TenantId $tenant -ClientId $cid -Certificate $cert -Audience $aud
      }
    } catch {
      # 🔴 SEC-12: KEEP the reason. This was Write-Verbose only, so the one fact that explained
      # everything downstream was discarded at the moment it was known.
      $primaryErr = "$($_.Exception.Message)"
      Write-Verbose "PIM-Rest primary auth failed for ${Resource}: $primaryErr"
    }
  }

  # =====================================================================================
  # 🔴 SEC-12 -- AN EXPLICIT IDENTITY THAT CANNOT BE HONOURED IS AN ERROR, NOT A CUE TO
  # BECOME SOMEBODY ELSE.
  #
  # MEASURED 2026-08-28: a caller asked for the internal tenant + the PIM engine
  # client id + its certificate thumbprint, and got back a token for ANOTHER company's tenant
  # (A DIFFERENT COMPANY's tenant) with a different appid. Nothing in the return value
  # said so. The certificate had failed to resolve, the failure went to Write-Verbose, and the
  # "dev convenience" command-line fallback (since removed, REQ 100.42) then minted a token for whatever
  # subscription happened to be that tool's DEFAULT context -- which on the dev machine is frequently another
  # tenant entirely.
  #
  # 🔑 THE POINT IS NOT THAT THE FALLBACK EXISTS. It is that it ran AFTER the caller had named a
  # tenant, a client id and a credential. That caller has said exactly who it wants to be, and
  # answering with a different principal is WORSE than answering with an error: the token works,
  # so the failure surfaces far away as "Login failed" or "permission denied" and reads like an
  # RBAC problem. It cost a session's time to chase, and the answer was three layers up.
  #
  # 📌 Same family as BUG-34, which fixed precisely this shape one layer down in
  # New-PimSqlConnection ("a valid-but-wrong-tenant token was taken, so the explicitly
  # configured SPN never got a turn") and left the command-line branch here standing (removed since, REQ 100.42).
  # =====================================================================================
  if (-not $res -and $explicitIdentity) {
    $why = if ("$thumb".Trim() -and -not $cert) {
             "certificate '$thumb' was not found in CurrentUser\My or LocalMachine\My, or has no usable private key"
           } elseif ($primaryErr) { $primaryErr } else { 'the credential was not accepted' }
    throw ("PIM-Rest: REFUSING to fall back to an ambient identity for '$Resource'. " +
           "An explicit identity was requested (tenant '$tenant', client '$cid') and could not be honoured: $why. " +
           'Fix the credential rather than letting the call authenticate as somebody else -- a token for the wrong ' +
           'principal succeeds and then fails far away as a permissions error.')
  }

  # §100.42 / framework §12.17 (owner 2026-10-09: "modern single connect only"): the command-line fallback ("reuse
  # whoever is signed in to the CLI") is GONE. A signed-in setup run does not borrow a tool's session any more:
  # tools\setup\_PimSignedIn.ps1 (Set-PimSignedInGlobals) REGISTERS its token source here --
  # the Invardia Support-app session's Get-InvardiaSupportToken when that session is open in the shell, otherwise the
  # person's own browser sign-in (Get-PimInteractiveToken, auth-code + PKCE). Only reached when NO explicit identity
  # was requested (the refusal above still throws for one that cannot be honoured).
  # 2026-10-10: a setup step's OWN child processes (e.g. the schema step) inherit PIM_HANDOFF_TOKENS from the build -- answer
  # from it first, so no grandchild process opens a silent browser sign-in.
  # 8.13: either shape is read -- the build's own (audience -> token string) or the bootstrap's (audience -> {access_token,
  # expires_on}) -- and a token whose tid is not the requested tenant is never returned (SEC-12).
  if (-not $res -and "$env:PIM_HANDOFF_TOKENS".Trim() -and -not $explicitIdentity) {
    try {
      $ho = "$env:PIM_HANDOFF_TOKENS" | ConvertFrom-Json
      foreach ($pp in $ho.PSObject.Properties) {
        if ("$($pp.Name)".TrimEnd('/').ToLowerInvariant() -eq "$aud".TrimEnd('/').ToLowerInvariant()) {
          # REQ 100.76: with a handed-over refresh token, Azure SQL is never answered from a pre-minted access token.
          if ("$aud" -match '(?i)database\.windows\.net' -and "$env:PIM_HANDOFF_REFRESH".Trim()) { continue }
          $hv = if ($pp.Value -is [string]) { "$($pp.Value)" } elseif ($pp.Value -and $pp.Value.PSObject.Properties['access_token']) { "$($pp.Value.access_token)" } else { '' }
          if (-not "$hv".Trim()) { continue }
          $hvTid = Get-PimTokenTenantId -Token $hv
          if ("$tenant".Trim() -and $hvTid -and $hvTid -ne "$tenant".Trim().ToLowerInvariant()) { Write-Verbose "PIM_HANDOFF_TOKENS: the token for $aud is for another tenant -- not used"; continue }
          return $hv
        }
      }
    } catch { Write-Verbose "PIM_HANDOFF_TOKENS unreadable: $($_.Exception.Message)" }
  }
  # REQ 100.76: a step's child process with no token source of its own mints from the handed-over refresh token -- silently,
  # at the moment it is asked (never a browser window from here).
  if (-not $res -and "$env:PIM_HANDOFF_REFRESH".Trim() -and -not $explicitIdentity -and -not ($global:PIM_TokenProvider -is [scriptblock])) {
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant -RefreshOnly } catch { Write-Verbose "PIM_HANDOFF_REFRESH exchange for ${Resource} failed: $($_.Exception.Message)" }
  }
  if (-not $res -and ($global:PIM_TokenProvider -is [scriptblock])) {
    $pt = $null
    try { $pt = & $global:PIM_TokenProvider $aud $tenant } catch { throw "PIM-Rest: the signed-in token source failed for '$Resource': $($_.Exception.Message)" }
    if ($pt -is [string]) { $pt = [pscustomobject]@{ token = $pt; expiresUtc = (Get-Date).ToUniversalTime().AddMinutes(30) } }
    if ($pt -and "$($pt.token)".Trim()) {
      # 🔒 VERIFY IT (SEC-12): asking for a tenant is not the same as being given one.
      $claimed = Get-PimTokenTenantId -Token "$($pt.token)"
      if ("$tenant".Trim() -and $claimed -and ($claimed -ne "$tenant".Trim().ToLowerInvariant())) {
        throw "PIM-Rest: REFUSED a signed-in token for '$Resource': it belongs to tenant $claimed, not the requested $tenant."
      }
      $res = $pt
    }
  }
  # LAST-RESORT interactive prompt — ONLY when an attended caller opts in via
  # $global:PIM_InteractiveFallback (the interactive admin tools set this; the engine /
  # headless cron NEVER does, so an unattended run still fails fast instead of hanging on
  # a browser prompt). This is what makes the admin deploy scripts "just sign me in" when
  # no MI/secret/cert token is available, rather than throwing.
  if (-not $res -and $global:PIM_InteractiveFallback) {
    Write-Host "PIM-Rest: no MI/secret/cert token for '$Resource' -- falling back to interactive sign-in..." -ForegroundColor Yellow
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant } catch { Write-Verbose "PIM-Rest interactive fallback failed for ${Resource}: $($_.Exception.Message)" }
  }
  # MI-TOKEN-TRANSIENT: carry the primary credential's own answer -- without it the record named no cause (SUP-2026-00323).
  if (-not $res) { throw ("PIM-Rest: could not acquire a token for '$Resource'. Provide a managed identity, ClientId + certificate (+TenantId), the Invardia Support-app session, or -Interactive (browser sign-in)." + $(if ($primaryErr) { " ($primaryErr)" } else { '' })) }

  $script:PimTokenCache[$key] = $res
  return $res.token
}

# ---- REST error reporting (BUG-27) ----------------------------------------
# A REST failure used to be logged as, verbatim:
#     PUT https://management.azure.com/.../roleEligibilityScheduleRequests/...
#         -> HTTP 409 :
# The colon is where the reason should be. ARM had actually answered
#     { "error": { "code": "ReadOnlyDisabledSubscription",
#                  "message": "The subscription '...' is disabled and therefore
#                              marked as read only." } }
# and the engine threw it away. Three wrong hypotheses were checked with live ARM
# queries before replaying the same PUT by hand produced the answer instantly.
#
# The whole audit rests on believing what the engine reports: a scope reporting
# "errors=1" with no cause is indistinguishable from a real code defect. In a
# customer tenant the same line is a support round-trip instead of a fix.
# ---------------------------------------------------------------------------

function Get-PimRestErrorBody {
  <#
    Read the error body from a terminating REST error, from BOTH sources.

    🪤 The old code was `if (ErrorDetails.Message) {...} else { read the stream }`. On
    Windows PowerShell 5.1 ErrorDetails.Message is frequently PRESENT BUT EMPTY, so the
    else-branch never ran and the stream -- which held the real answer -- was never read.
    Take the LONGER of the two instead of trusting either.
  #>
  [CmdletBinding()] param([Parameter(Mandatory)][object]$ErrorRecord)
  $fromDetails = ''
  try { if ($ErrorRecord.ErrorDetails) { $fromDetails = "$($ErrorRecord.ErrorDetails.Message)" } } catch {}
  $fromStream = ''
  try {
    $resp = $ErrorRecord.Exception.Response
    if ($resp) {
      $stream = $resp.GetResponseStream()
      if ($stream) {
        # The stream may already have been consumed; rewind when we are allowed to.
        try { if ($stream.CanSeek) { $stream.Position = 0 } } catch {}
        $sr = New-Object System.IO.StreamReader($stream)
        try { $fromStream = $sr.ReadToEnd() } finally { $sr.Dispose() }
      }
    }
  } catch {}
  if ("$fromStream".Trim().Length -gt "$fromDetails".Trim().Length) { return $fromStream }
  return $fromDetails
}

function Get-PimRestErrorDetail {
  <#
    PURE. Turn an ARM/Graph error body into the SHORT reason a human needs.

    Returns "<code> -- <message>", or $null when the body carries nothing usable (the
    caller must then say so explicitly rather than printing an empty reason).

    🔒 CODE + MESSAGE ONLY, NEVER THE WHOLE BODY. The raw body can carry subscription
    ids, principal ids and request ids; it is also mostly noise. code+message is the
    part that ends the diagnosis, so it is the right amount to log.

    Handles the shapes both APIs actually return:
      ARM      { "error": { "code": ..., "message": ... } }
      Graph    { "error": { "code": ..., "message": ..., "innerError": {...} } }
      flat     { "code": ..., "message": ... }
      odata    { "odata.error": { "code": ..., "message": { "value": ... } } }
      non-JSON (HTML error pages, plain text) -- returned trimmed + truncated.
  #>
  [CmdletBinding()] param([Parameter()][AllowNull()][AllowEmptyString()][string]$Body, [int]$MaxLength = 400)

  $raw = "$Body".Trim()
  if (-not $raw) { return $null }

  $obj = $null
  try { $obj = $raw | ConvertFrom-Json } catch { $obj = $null }

  # Property lookup is CASE-INSENSITIVE. `-contains` is not, and Azure is not consistent:
  # ARM/Graph send "message", some services send "Message". A case-sensitive check would
  # silently miss those and fall through to printing the raw body.
  $prop = {
    param($o, $name)
    try { foreach ($p in $o.PSObject.Properties) { if ("$($p.Name)" -ieq "$name") { return $p.Value } } } catch {}
    return $null
  }

  if ($obj) {
    $err = $null
    foreach ($k in @('error', 'odata.error')) {
      $v = & $prop $obj $k
      if ($null -ne $v) { $err = $v; break }
    }
    if ($null -eq $err) { $err = $obj }          # flat { code, message }

    $code = "$(& $prop $err 'code')".Trim()
    $m = & $prop $err 'message'
    $msg = ''
    if ($null -ne $m) {
      # odata nests the text one level deeper: message.value
      if ($m -isnot [string]) {
        $inner = & $prop $m 'value'
        $msg = if ($null -ne $inner) { "$inner".Trim() } else { "$m".Trim() }
      } else { $msg = "$m".Trim() }
    }

    if ($code -or $msg) {
      $joined = if ($code -and $msg) { "$code -- $msg" } elseif ($code) { $code } else { $msg }
      $joined = ($joined -replace '\s+', ' ').Trim()
      if ($joined.Length -gt $MaxLength) { $joined = $joined.Substring(0, $MaxLength) + '...' }
      return $joined
    }

    # Valid JSON that carries no code and no message -- e.g. "{}". Echoing it back would
    # print "HTTP 409 : {}", which is exactly as useless as the empty colon this whole
    # function exists to eliminate. Report NOTHING USABLE and let the caller say so.
    $hasAny = $false
    try { $hasAny = @($obj.PSObject.Properties).Count -gt 0 } catch {}
    if (-not $hasAny) { return $null }
  }

  # Not JSON (HTML error page, plain text), or JSON whose useful part we could not name:
  # return it trimmed + truncated. Better than nothing, and still bounded -- an error
  # page must not flood the log.
  $flat = ($raw -replace '\s+', ' ').Trim()
  if (-not $flat) { return $null }
  if ($flat.Length -gt $MaxLength) { $flat = $flat.Substring(0, $MaxLength) + '...' }
  return $flat
}

# ---- data plane -----------------------------------------------------------
# Every REST call is bounded (see Invoke-PimRest). $global:PIM_RestTimeoutSec overrides; floor 10 s, default 180 s.
function Get-PimRestTimeoutSec {
  $v = 0; if ($global:PIM_RestTimeoutSec) { [void][int]::TryParse("$($global:PIM_RestTimeoutSec)", [ref]$v) }
  if ($v -ge 10) { return $v }
  return 180
}
function Test-PimRestTimeoutError {
  # pwsh 7: HttpClient's timeout surfaces as TaskCanceledException / TimeoutException ("The request was canceled due to the
  # configured HttpClient.Timeout"); PS 5.1: WebException status Timeout ("The operation has timed out").
  param($ErrorRecord)
  $e = $null; try { $e = $ErrorRecord.Exception } catch { }
  while ($e) {
    if ($e -is [System.TimeoutException] -or $e -is [System.Threading.Tasks.TaskCanceledException]) { return $true }
    if ($e -is [System.Net.WebException] -and $e.Status -eq [System.Net.WebExceptionStatus]::Timeout) { return $true }
    $e = $e.InnerException
  }
  return ("$($ErrorRecord)" -match 'HttpClient\.Timeout|operation has timed out|request was canceled')
}
function Test-PimRestNetworkError {
  # UPDATER-ARM-RETRY (2026-10-21, internal): a call that failed BELOW HTTP (no status code) on a one-off network fault --
  # "Cannot assign requested address" (no free local port), connection refused / reset, a name that did not resolve. It failed
  # the updater's PATCH of ca-pim-manager once and nothing retried. Connect-level faults never reached the service, so any method
  # is safe to send again; a reset AFTER the request was sent is retried only for an idempotent method (never a POST).
  param($ErrorRecord, [string]$Method = 'GET')
  $connect = 'Cannot assign requested address|No connection could be made|actively refused|Connection refused|No such host is known|Name or service not known|nodename nor servname|Temporary failure in name resolution|Network is unreachable|NameResolutionFailure|ConnectFailure'
  $reset   = 'forcibly closed|Connection reset|connection was closed|transport connection|Broken pipe|An error occurred while sending the request|ReceiveFailure|SendFailure'
  $text = New-Object System.Collections.Generic.List[string]
  $e = $null; try { $e = $ErrorRecord.Exception } catch { }
  $isSock = $false
  while ($e) {
    $text.Add("$($e.Message)")
    if ($e -is [System.Net.Sockets.SocketException]) { $isSock = $true }
    if ($e -is [System.Net.WebException]) { $text.Add("$($e.Status)") }
    $e = $e.InnerException
  }
  $text.Add("$ErrorRecord")
  $all = $text -join ' | '
  if ($all -match $connect) { return $true }
  $idem = @('GET','HEAD','PUT','PATCH','DELETE','OPTIONS') -contains "$Method".ToUpperInvariant()
  if ($idem -and ($isSock -or $all -match $reset)) { return $true }
  return $false
}
function Get-PimRestNetworkRetryMax { <# PURE. Extra tries for a network fault (a literal). #> return 3 }
# §33.0 MORE TELEMETRY round 2 (owner "add relevant. i want data"): RETRIES PER HTTP CODE. Every 429 / 5xx retry of a GRAPH
# call (Invoke-PimRest's backoff loop and the $batch sub-requests) is counted in this process ($global: -- a dot-sourced
# function's $script: follows the caller's scope); the scheduler persists the counts after every job run into hourly
# buckets (pim.Settings 'GraphRetryCounts', Save-PimRestRetryCounts), and the heartbeat sends graphThrottled24h = the 429s
# of the last 24 hours. Counts only -- no URL, no tenant, no body.
function Add-PimRestRetryCount {
  param([int]$Code, [string]$Resource = 'graph')
  try {
    if ("$Resource" -ne 'graph') { return }
    $k = if ($Code -eq 429) { 'r429' } elseif ($Code -ge 500) { 'r5xx' } else { '' }
    if (-not $k) { return }
    if (-not ($global:PimRestRetryCounts -is [hashtable])) { $global:PimRestRetryCounts = @{ r429 = [long]0; r5xx = [long]0 } }
    $global:PimRestRetryCounts[$k] = [long]$global:PimRestRetryCounts[$k] + 1
  } catch { }
}
function Get-PimRestRetryCounts {
  # A COPY of this process's not-yet-persisted counts: @{ r429; r5xx } (zeros when nothing was counted).
  $c = $global:PimRestRetryCounts
  if (-not ($c -is [hashtable])) { return @{ r429 = [long]0; r5xx = [long]0 } }
  return @{ r429 = [long]$c['r429']; r5xx = [long]$c['r5xx'] }
}
function Get-PimRestRetryBucketHours { <# PURE. How many hourly buckets the record keeps (a literal). #> return 48 }
function Merge-PimRestRetryBuckets {
  <#
    PURE. The stored record (raw JSON text, or $null / '' for none) plus -Add @{ r429; r5xx } in the bucket of -NowUtc's hour
    -> the new record as JSON text: { sinceUtc; hours = { 'yyyy-MM-ddTHH:00:00Z' = { r429; r5xx } } }. Buckets older than
    Get-PimRestRetryBucketHours are dropped; sinceUtc (when counting started here) is kept. A stored value that is not
    the record's shape starts a new record. Built as text (no DateTime round-trip through ConvertFrom-Json on PS 7).
  #>
  param([AllowNull()][string]$Existing, [hashtable]$Add = @{}, [datetime]$NowUtc = [datetime]::UtcNow)
  $now = $NowUtc.ToUniversalTime()
  $cut = $now.AddHours(-1 * (Get-PimRestRetryBucketHours))
  $inv = [System.Globalization.CultureInfo]::InvariantCulture
  $styles = [System.Globalization.DateTimeStyles]::AssumeUniversal -bor [System.Globalization.DateTimeStyles]::AdjustToUniversal
  $since = $now.ToString('yyyy-MM-ddTHH:mm:ssZ', $inv)
  $hours = New-Object 'System.Collections.Generic.SortedDictionary[string,object]' ([System.StringComparer]::Ordinal)
  if ("$Existing".Trim()) {
    try {
      $o = "$Existing" | ConvertFrom-Json
      if ($null -ne $o -and $o.PSObject.Properties['hours']) {
        $sv = $o.sinceUtc
        if ($sv -is [datetime]) { $since = $sv.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) }
        elseif ("$sv".Trim()) { $d0 = [datetime]::MinValue; if ([datetime]::TryParse("$sv", [System.Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d0)) { $since = $d0.ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) } }
        if ($null -ne $o.hours) {
          foreach ($p in @($o.hours.PSObject.Properties)) {
            $d = [datetime]::MinValue
            if (-not [datetime]::TryParse("$($p.Name)", [System.Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { continue }
            if ($d -lt $cut) { continue }
            $a = 0L; $b = 0L
            [void][long]::TryParse("$($p.Value.r429)", [ref]$a); [void][long]::TryParse("$($p.Value.r5xx)", [ref]$b)
            $hours[$d.ToString('yyyy-MM-ddTHH:00:00Z', $inv)] = @{ r429 = [math]::Max(0L, $a); r5xx = [math]::Max(0L, $b) }
          }
        }
      }
    } catch { $hours.Clear() }
  }
  $key = $now.ToString('yyyy-MM-ddTHH:00:00Z', $inv)
  $ad = 0L; $bd = 0L; [void][long]::TryParse("$($Add['r429'])", [ref]$ad); [void][long]::TryParse("$($Add['r5xx'])", [ref]$bd)
  if ($ad -gt 0 -or $bd -gt 0) {
    $cur = if ($hours.ContainsKey($key)) { $hours[$key] } else { @{ r429 = 0L; r5xx = 0L } }
    $hours[$key] = @{ r429 = [long]$cur.r429 + [math]::Max(0L, $ad); r5xx = [long]$cur.r5xx + [math]::Max(0L, $bd) }
  }
  $parts = @(foreach ($k in $hours.Keys) { '"{0}":{{"r429":{1},"r5xx":{2}}}' -f $k, [long]$hours[$k].r429, [long]$hours[$k].r5xx })
  return ('{{"sinceUtc":"{0}","hours":{{{1}}}}}' -f $since, ($parts -join ','))
}
function Save-PimRestRetryCounts {
  <#
    Persist this process's counts into pim.Settings 'GraphRetryCounts' (compare-and-set, 5 tries -- several tick executions
    run at once) and zero what was saved. Writes ONLY when something was counted (a quiet run touches nothing -- no read,
    no write), so "no record" = no retry was ever recorded here. Never throws.
    Returns @{ saved; reason }. -Read { param($cs,$name) } / -Write { param($cs,$name,$new,$expected) -> rows }: test seams.
  #>
  param([string]$ConnectionString = '', [datetime]$NowUtc = [datetime]::UtcNow, [scriptblock]$Read = $null, [scriptblock]$Write = $null)
  try {
    $c = Get-PimRestRetryCounts
    $any = ([long]$c.r429 + [long]$c.r5xx) -gt 0
    if (-not $any) { return @{ saved = $false; reason = 'nothing counted' } }
    $cs = "$ConnectionString"
    if (-not $cs.Trim() -and (Get-Command Get-PimSqlSettingsConnectionString -ErrorAction SilentlyContinue)) { $cs = "$(Get-PimSqlSettingsConnectionString)" }
    if (-not $cs.Trim()) { return @{ saved = $false; reason = 'no SQL store' } }
    if (-not $Read) {
      if (-not (Get-Command Get-PimSqlSettingRaw -ErrorAction SilentlyContinue)) { return @{ saved = $false; reason = 'the settings reader is not loaded' } }
      $Read = { param($s, $n) Get-PimSqlSettingRaw -ConnectionString $s -Name $n }
    }
    if (-not $Write) {
      if (-not (Get-Command Set-PimSqlSettingIfUnchanged -ErrorAction SilentlyContinue)) { return @{ saved = $false; reason = 'the settings writer is not loaded' } }
      $Write = { param($s, $n, $new, $exp) Set-PimSqlSettingIfUnchanged -ConnectionString $s -Name $n -NewValueJson $new -ExpectedValueJson $exp }
    }
    for ($i = 0; $i -lt 5; $i++) {
      $raw = & $Read $cs 'GraphRetryCounts'
      $new = Merge-PimRestRetryBuckets -Existing $raw -Add $c -NowUtc $NowUtc
      $n = 0; try { $n = [int](@(& $Write $cs 'GraphRetryCounts' $new $raw) | Select-Object -Last 1) } catch { $n = 0 }
      if ($n -ge 1) {
        if ($global:PimRestRetryCounts -is [hashtable]) {
          $global:PimRestRetryCounts['r429'] = [math]::Max(0L, [long]$global:PimRestRetryCounts['r429'] - [long]$c.r429)
          $global:PimRestRetryCounts['r5xx'] = [math]::Max(0L, [long]$global:PimRestRetryCounts['r5xx'] - [long]$c.r5xx)
        }
        return @{ saved = $true; reason = '' }
      }
    }
    return @{ saved = $false; reason = 'another writer kept winning -- kept for the next run' }
  } catch { return @{ saved = $false; reason = "$($_.Exception.Message)" } }
}
function Invoke-PimRest {
  [CmdletBinding()]
  param(
    [string]$Method = 'GET',
    [Parameter(Mandatory)][string]$Url,
    [object]$Body,
    [string]$Resource = 'graph',
    [hashtable]$Headers = @{},
    [switch]$All,                # follow @odata.nextLink / nextLink, aggregate .value
    [int]$MaxRetry = 5,
    # Authenticate THIS call as the host's managed identity even when an engine SPN is configured
    # (mail send, operator decision 2026-09-13: the hosted engine sends as its managed identity).
    [switch]$UseManagedIdentity
  )
  # Keep a scheduler lease alive through a long live read (minutes of paged calls). No-op outside
  # a leased tick; time-gated in Invoke-PimSchedulerLeaseHeartbeat (PIM-Scheduler.ps1).
  if ($global:PIM_LeaseHeartbeat -and (Get-Command Invoke-PimSchedulerLeaseHeartbeat -ErrorAction SilentlyContinue)) { [void](Invoke-PimSchedulerLeaseHeartbeat) }
  $token = if ($UseManagedIdentity) { Get-PimRestToken -Resource $Resource -UseManagedIdentity } else { Get-PimRestToken -Resource $Resource }
  $h = @{ Authorization = "Bearer $token" } + $Headers
  $agg = New-Object System.Collections.Generic.List[object]
  $next = $Url
  while ($next) {
    $attempt = 0; $netTry = 0
    while ($true) {
      try {
        # 🔴 2026-10-02: NO -TimeoutSec = wait FOREVER on pwsh 7. One Graph call that never answered froze the hybrid worker's
        # continuous AD sync for 22 hours (process alive, task "Running", IgnoreNew -> never restarted). Every call is bounded now.
        $args = @{ Method = $Method; Uri = $next; Headers = $h; TimeoutSec = (Get-PimRestTimeoutSec) }
        # (see Get-PimRestErrorBody / Get-PimRestErrorDetail above for the failure path)
        if ($null -ne $Body -and $Method -ne 'GET') {
          $args.Body = if ($Body -is [string]) { $Body } else { $Body | ConvertTo-Json -Depth 20 }
          $args.ContentType = 'application/json'
        }
        $resp = Invoke-RestMethod @args
        break
      } catch {
        $code = $null; try { $code = [int]$_.Exception.Response.StatusCode } catch {}
        # BUG-27: surface the API error body. Try BOTH sources and keep the longer of the
        # two -- on 5.1 ErrorDetails.Message is frequently present but EMPTY, and the old
        # `if/else` took it and never looked at the stream, which is how a real ARM
        # explanation became the bare log line "-> HTTP 409 :" (note the empty colon).
        $body = Get-PimRestErrorBody -ErrorRecord $_
        # retry transient + freshly-created-principal replication (ARM 400 PrincipalNotFound)
        $isReplDelay = ($code -eq 400 -and "$body" -match 'PrincipalNotFound|does not exist in the directory')
        # a call that hit -TimeoutSec is retried ONCE (a second full wait is the most a stuck endpoint may cost), then fails
        $isTimeout = (-not $code) -and (Test-PimRestTimeoutError -ErrorRecord $_)
        if ($isTimeout -and $attempt -lt 1) { $attempt++; continue }
        if ($isTimeout) { throw "$Method $next -> timed out after $(Get-PimRestTimeoutSec) s (twice) -- the service did not answer" }
        # UPDATER-ARM-RETRY: a one-off network fault (no HTTP status) is tried again with a short backoff (5, 10, 20 s)
        if ((-not $code) -and (Test-PimRestNetworkError -ErrorRecord $_ -Method $Method)) {
          if ($netTry -lt (Get-PimRestNetworkRetryMax)) { Start-Sleep -Seconds ([int](5 * [Math]::Pow(2, $netTry))); $netTry++; continue }
        }
        if (($code -eq 429 -or $code -ge 500 -or $isReplDelay) -and $attempt -lt $MaxRetry) {
          if ($code -eq 429 -or $code -ge 500) { Add-PimRestRetryCount -Code ([int]$code) -Resource $Resource }   # §33.0 round 2
          $wait = [Math]::Min(60, [Math]::Pow(2, $attempt + 1))
          try { $ra = [int]("$($_.Exception.Response.Headers['Retry-After'])"); if ($ra -gt 0) { $wait = $ra } } catch {}
          Start-Sleep -Seconds $wait; $attempt++; continue
        }
        # section 9 missing-role hint: on a 403 / insufficient-privileges, append the EXACT
        # Graph app-role to grant (engine SPN, app-only) so the operator isn't left
        # guessing. Best-effort: only when the hint helper is loaded (PIM-Functions /
        # PIM-AuthDiagnostics dot-sourced) and the failure is a permissions failure.
        $hintText = ''
        if (Get-Command Get-PimMissingRoleHint -ErrorAction SilentlyContinue) {
            try {
                $appOnly = -not [bool]$global:PIM_Interactive
                $h = Get-PimMissingRoleHint -Path $next -StatusCode ([int]("$code")) -ErrorBody "$body" -AppOnly:$appOnly
                if ($h) { $hintText = "  >> $($h.Hint)" }
            } catch {}
        }
        # BUG-27: report error.code + error.message, NOT the raw body. The raw body can
        # carry ids and is usually mostly noise; code+message is the part that ends the
        # diagnosis. And a body that yields nothing usable must SAY SO -- "HTTP 409 :"
        # with an empty reason reads as "no reason exists", which sent a whole session
        # chasing three wrong hypotheses while ARM had the answer all along
        # ("ReadOnlyDisabledSubscription -- the subscription is disabled and therefore
        # marked as read only").
        $detail = Get-PimRestErrorDetail -Body $body
        # 2026-09-21 (operator: "can you provide graph or arm errors in here as i have nothing to work with"): the
        # thrown message stays code+message (above), but the full body of the LAST failure is kept for a caller that
        # needs more -- e.g. a policy-rule PATCH that adds the request-id and what it sent (Invoke-PimPolicyRulePatch).
        # 100.50: the Retry-After of that failure too (seconds; 0 = none) -- an ARM write refused with 409 OperationInProgress
        # is waited out by Invoke-PimArmBusyRetry (PIM-ArmContainerApps.ps1), which honours it when the service sent one.
        $raLast = 0
        try { $d = $_.Exception.Response.Headers.RetryAfter.Delta; if ($d) { $raLast = [int][Math]::Ceiling($d.TotalSeconds) } } catch { }
        if (-not $raLast) { try { [void][int]::TryParse("$($_.Exception.Response.Headers['Retry-After'])", [ref]$raLast) } catch { } }
        $global:PimLastRestError = [pscustomobject]@{ method = $Method; url = $next; status = $code; body = "$body"; atUtc = [datetime]::UtcNow; retryAfter = $raLast }
        if ($detail) { throw "$Method $next -> HTTP $code : $detail$hintText" }
        throw "$Method $next -> HTTP $code : (no error body returned by the service)$hintText"
      }
    }
    if (-not $All) { return $resp }
    if ($null -ne $resp.value) { foreach ($v in $resp.value) { $agg.Add($v) } } else { $agg.Add($resp) }
    $next = $null
    if ($resp.'@odata.nextLink') { $next = $resp.'@odata.nextLink' }
    elseif ($resp.nextLink)      { $next = $resp.nextLink }
  }
  return $agg.ToArray()
}

function ConvertTo-PimSdkShape {
  # Make a Graph REST object look like a Graph PowerShell SDK object: add a
  # PascalCase alias for every camelCase property (userPrincipalName ->
  # UserPrincipalName, displayName -> DisplayName, id -> Id) so existing engine
  # filters/consumers that expect SDK casing keep working over pure REST.
  param([Parameter(ValueFromPipeline)][object]$InputObject)
  process {
    if ($null -eq $InputObject) { return }
    $o = [ordered]@{}
    foreach ($p in $InputObject.PSObject.Properties) {
      $o[$p.Name] = $p.Value
      if ($p.Name.Length -ge 1) {
        $pascal = $p.Name.Substring(0,1).ToUpperInvariant() + $p.Name.Substring(1)
        if (-not $o.Contains($pascal)) { $o[$pascal] = $p.Value }
      }
    }
    [pscustomobject]$o
  }
}

function Invoke-PimGraph {
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[switch]$All,[switch]$Beta,[hashtable]$Headers=@{},[switch]$UseManagedIdentity)
  $base = if ($Beta) { 'https://graph.microsoft.com/beta' } else { 'https://graph.microsoft.com/v1.0' }
  $url = if ($Path -match '^https?://') { $Path } else { "$base$Path" }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'graph' -All:$All -Headers $Headers -UseManagedIdentity:$UseManagedIdentity
}
function Test-PimGraphBatchReadsEnabled {
  # Kill switch for the batched live reads (pim.Settings / $global:PIM_ / env 'GraphBatchReads').
  # ON by default; 'false' makes every caller take its original one-request-per-path loop.
  $v = $null
  if (Get-Command Get-PimPolicySetting -ErrorAction SilentlyContinue) { try { $v = Get-PimPolicySetting -Name 'GraphBatchReads' -Default $null } catch { $v = $null } }
  elseif ($null -ne $global:PIM_GraphBatchReads) { $v = $global:PIM_GraphBatchReads }
  elseif ("$env:PIM_GraphBatchReads".Trim()) { $v = $env:PIM_GraphBatchReads }
  return -not ("$v".Trim() -match '^(?i)(false|0|no|off|disabled?)$')
}

function Invoke-PimGraphBatchGet {
  <#
    Run many Graph GETs through /$batch (20 per round-trip, Graph's maximum) and return ONE result per
    input path, IN INPUT ORDER: { path; ok; status; items; body; error }.
      items  = what `Invoke-PimGraph -All -Path <path>` returns: the aggregated .value across every
               @odata.nextLink page, or the body itself when it carries no .value.
      body   = what `Invoke-PimGraph -Path <path>` returns (the first page / the single object).
    A sub-request that is throttled (429), failed server-side (5xx) or came back missing is collected; the
    largest Retry-After is waited ONCE (max 30 s) and the collected items are sent again as a batch, up to 3
    rounds (§70.9). Only what is still unanswered after that is re-run on its own through Invoke-PimGraph,
    which owns the retry/backoff -- so a batch never loses a read that the sequential loop would have got.
    $script:PimBatchStats holds the counters of the last call. Any other 4xx is a final failure (ok=$false, error set), exactly
    what the sequential loop's `try { Invoke-PimGraph ... } catch { }` produced.
    A $batch response without `responses` (a proxy, a stub, a host that does not batch) falls back to
    the sequential path for that slice.
  #>
  param([Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Paths, [ValidateRange(1, 20)][int]$BatchSize = 20,
        # SCHEMA-QUIESCE-LONG-SNAPSHOT (2): a long read (the snapshot's ~36k group reads on a big tenant) says it is alive.
        # With a label, one "[graph-batch] <label>: progress ..." line at least every $script:PimBatchProgressSeconds (default
        # 300 s). No label = no line (every other caller stays as it was).
        [AllowEmptyString()][string]$ProgressLabel = '')
  $n = @($Paths).Count
  $results = New-Object object[] $n
  if ($n -eq 0) { return ,$results }
  $single = {
    param([string]$p)
    try {
      $first = Invoke-PimGraph -Path $p
      $items = New-Object System.Collections.Generic.List[object]
      $pg = $first
      while ($null -ne $pg) {
        if ($pg.PSObject -and $pg.PSObject.Properties['value']) { foreach ($v in @($pg.value)) { $items.Add($v) } } else { $items.Add($pg) }
        $nl = $null; if ($pg.PSObject -and $pg.PSObject.Properties['@odata.nextLink']) { $nl = "$($pg.'@odata.nextLink')" }
        if (-not $nl) { break }
        $pg = Invoke-PimGraph -Path $nl
      }
      [pscustomobject]@{ path = $p; ok = $true; status = 200; items = $items.ToArray(); body = $first; error = $null }
    } catch {
      [pscustomobject]@{ path = $p; ok = $false; status = 0; items = @(); body = $null; error = "$($_.Exception.Message)" }
    }
  }
  # 🔴 §70.9 (2026-09-13) -- THROTTLED ITEMS ARE WAITED OUT AND RE-BATCHED, NOT FIRED ONE BY ONE.
  # A 429 / 5xx sub-response used to be re-run IMMEDIATELY as its own single request, ignoring the Retry-After the
  # sub-response carried -- so under throttling a 20-item round-trip became up to 20 more calls into the same
  # throttle, each backing off on its own (2/4/8/16/32 s). Measured on internal: ~10 s per round-trip on the
  # group-membership read (35 round-trips, ~6 min) and the policy read (~570 s), with the cause invisible because
  # nothing counted the throttling. Now: collect the throttled items, wait the largest Retry-After once (bounded),
  # send them again AS A BATCH (up to 3 rounds), and only then fall back to the single-request path. Every call that
  # was throttled or slow says so in one [graph-batch] line.
  $sw = [System.Diagnostics.Stopwatch]::StartNew()
  $script:PimBatchStats = @{ roundTrips = 0; throttled = 0; serverErrors = 0; retryRounds = 0; waitedSeconds = 0; singles = 0; pacedSeconds = 0; batchSize = $BatchSize; progressLines = 0 }
  $progEvery = if ($null -ne $script:PimBatchProgressSeconds -and "$($script:PimBatchProgressSeconds)" -match '^\d+$') { [int]$script:PimBatchProgressSeconds } else { 300 }
  $progLast = 0.0
  $progress = {
    if (-not "$ProgressLabel".Trim()) { return }
    $el = $sw.Elapsed.TotalSeconds
    if (($el - $progLast) -lt $progEvery) { return }
    Set-Variable -Name progLast -Value $el -Scope 1
    $answered = 0; foreach ($x in $results) { if ($null -ne $x) { $answered++ } }
    $script:PimBatchStats.progressLines++
    Write-Host ("  [graph-batch] {0}: progress -- {1} of {2} reads answered, {3} round-trips, {4} throttled, {5:N1} min so far" -f $ProgressLabel, $answered, $n, $script:PimBatchStats.roundTrips, $script:PimBatchStats.throttled, ($el / 60.0)) -ForegroundColor DarkGray
  }
  # 🔴 PACING (2026-09-27, internal, measured in Log Analytics): the first pass fired every round-trip back to back, so once
  # Graph started throttling, almost every later round-trip came back 429 too -- two 712-path reads per drift snapshot
  # (group memberships, group policies) each drew ~1,240 throttled answers, ~190 single fallbacks and ~225 s. Now a
  # round-trip that came back throttled is followed by a pause (its Retry-After, at most 10 s) before the NEXT round-trip.
  # The pauses share a 120 s budget per call; once it is spent the reader behaves as before (never slower than unpaced).
  # Tunables (script scope, for measuring on a live tenant): the pause cap and the per-call budget.
  $paceCap = if ($script:PimBatchPaceMaxSeconds -gt 0) { [int]$script:PimBatchPaceMaxSeconds } else { 10 }
  $paceBudget = if ($script:PimBatchPaceBudgetSeconds -gt 0) { [int]$script:PimBatchPaceBudgetSeconds } else { 120 }
  $pace = {
    param([int]$RetryAfter)
    if ($script:PimBatchStats.pacedSeconds -ge $paceBudget) { return }
    $p = [Math]::Min($paceCap, [Math]::Max(1, $RetryAfter))
    $p = [Math]::Min($p, $paceBudget - $script:PimBatchStats.pacedSeconds)
    $script:PimBatchStats.pacedSeconds += $p; $script:PimBatchStats.waitedSeconds += $p
    if ($script:PimBatchSleep -is [scriptblock]) { & $script:PimBatchSleep $p } else { Start-Sleep -Seconds $p }
  }
  $sendBatch = {
    param([int[]]$Indexes)
    $pending = New-Object System.Collections.Generic.List[int]   # throttled / missing -> retry
    $maxRetryAfter = 0
    $requests = New-Object System.Collections.Generic.List[object]
    foreach ($i in $Indexes) {
      $rel = ("$($Paths[$i])" -replace '^https://graph\.microsoft\.com/(v1\.0|beta)', '')
      $requests.Add(@{ id = "$i"; method = 'GET'; url = $rel })
    }
    $resp = $null
    $script:PimBatchStats.roundTrips++
    try { $resp = Invoke-PimGraph -Method POST -Path 'https://graph.microsoft.com/v1.0/$batch' -Body @{ requests = $requests.ToArray() } } catch { $resp = $null }
    $subs = $null
    if ($null -ne $resp -and $resp.PSObject -and $resp.PSObject.Properties['responses']) { $subs = @($resp.responses) }
    if ($null -eq $subs) { return [pscustomobject]@{ pending = @(); maxRetryAfter = 0; batched = $false } }   # no batch support -> singles
    $want = @{}; foreach ($i in $Indexes) { $want[$i] = $true }
    foreach ($br in $subs) {
        if ($null -eq $br) { continue }
        $idx = -1; if (-not [int]::TryParse("$($br.id)", [ref]$idx)) { continue }
        if (-not $want.ContainsKey($idx)) { continue }
        $status = 0; [void][int]::TryParse("$($br.status)", [ref]$status)
        if ($status -eq 429 -or $status -ge 500) {
          if ($status -eq 429) { $script:PimBatchStats.throttled++ } else { $script:PimBatchStats.serverErrors++ }
          Add-PimRestRetryCount -Code $status -Resource 'graph'   # §33.0 round 2: graphThrottled24h
          $ra = 0
          try { if ($br.headers) { foreach ($hp in $br.headers.PSObject.Properties) { if ("$($hp.Name)" -ieq 'Retry-After') { [void][int]::TryParse("$($hp.Value)", [ref]$ra) } } } } catch { }
          if ($ra -gt $maxRetryAfter) { $maxRetryAfter = $ra }
          $pending.Add($idx)
          continue
        }
        $body = $br.body
        if ($status -ge 200 -and $status -lt 300) {
          $items = New-Object System.Collections.Generic.List[object]
          $pg = $body; $ok = $true; $err = $null
          while ($null -ne $pg) {
            if ($pg.PSObject -and $pg.PSObject.Properties['value']) { foreach ($v in @($pg.value)) { $items.Add($v) } } else { $items.Add($pg) }
            $nl = $null; if ($pg.PSObject -and $pg.PSObject.Properties['@odata.nextLink']) { $nl = "$($pg.'@odata.nextLink')" }
            if (-not $nl) { break }
            try { $pg = Invoke-PimGraph -Path $nl } catch { $ok = $false; $err = "$($_.Exception.Message)"; break }
          }
          $results[$idx] = [pscustomobject]@{ path = $Paths[$idx]; ok = $ok; status = $status; items = @(if ($ok) { $items.ToArray() }); body = $body; error = $err }
        } else {
          $code = ''; $msg = ''
          if ($body -and $body.PSObject -and $body.PSObject.Properties['error'] -and $body.error) { $code = "$($body.error.code)"; $msg = "$($body.error.message)" }
          $results[$idx] = [pscustomobject]@{ path = $Paths[$idx]; ok = $false; status = $status; items = @(); body = $null
            error = ("GET {0} -> HTTP {1} : {2}{3}" -f $Paths[$idx], $status, $code, $(if ($msg) { " -- $msg" } else { '' })) }
        }
    }
    # an id Graph did not answer at all is retried like a throttled one
    foreach ($i in $Indexes) { if ($null -eq $results[$i] -and -not $pending.Contains($i)) { $pending.Add($i) } }
    return [pscustomobject]@{ pending = @($pending.ToArray()); maxRetryAfter = $maxRetryAfter; batched = $true }
  }
  $retryQueue = New-Object System.Collections.Generic.List[int]
  $maxRa = 0
  # 🔑 SHRINK ON THROTTLE (2.4.457, measured on a test environment with 712 PIM-for-Groups schedule reads): every batch size took the same
  # 259-287 s -- the tenant's own Graph ceiling (~2.7 reads/s), which no pacing beats -- but 20 per round-trip drew 444
  # throttled answers and 49 single fallbacks, 10 drew 63 and none, 5 drew 20 and none. So a read starts at $BatchSize and
  # halves it (down to 5) after each throttled round-trip: an unthrottled read keeps full batches, a throttled one stops
  # piling 429s onto the ceiling. $script:PimBatchStats.batchSize is the size it ended on.
  $curSize = $BatchSize
  $ofs = 0
  while ($ofs -lt $n) {
    $last = [Math]::Min($ofs + $curSize, $n) - 1
    $r = & $sendBatch -Indexes @($ofs..$last)
    $ofs = $last + 1
    & $progress
    foreach ($p in @($r.pending)) { $retryQueue.Add([int]$p) }
    if ($r.maxRetryAfter -gt $maxRa) { $maxRa = $r.maxRetryAfter }
    if (@($r.pending).Count) {
      if ($curSize -gt 5) { $curSize = [Math]::Max(5, [int][Math]::Floor($curSize / 2)) }
      if ($ofs -lt $n) { & $pace $r.maxRetryAfter }   # throttled: let it clear before the next
    }
  }
  $script:PimBatchStats.batchSize = $curSize
  # Up to 3 rounds: wait out the throttle ONCE for the whole queue, then send the queue again in batches.
  $round = 0
  while ($retryQueue.Count -gt 0 -and $round -lt 3) {
    $round++
    $script:PimBatchStats.retryRounds = $round
    $wait = [Math]::Min(30, [Math]::Max($maxRa, [int][Math]::Pow(2, $round)))
    $script:PimBatchStats.waitedSeconds += $wait
    if ($script:PimBatchSleep -is [scriptblock]) { & $script:PimBatchSleep $wait } else { Start-Sleep -Seconds $wait }   # test seam
    $queue = @($retryQueue.ToArray() | Where-Object { $null -eq $results[$_] })
    $retryQueue.Clear(); $maxRa = 0
    $o = 0
    while ($o -lt $queue.Count) {
      $slice = @($queue[$o..([Math]::Min($o + $curSize, $queue.Count) - 1)])
      $o += $slice.Count
      $r = & $sendBatch -Indexes $slice
      & $progress
      foreach ($p in @($r.pending)) { $retryQueue.Add([int]$p) }
      if ($r.maxRetryAfter -gt $maxRa) { $maxRa = $r.maxRetryAfter }
      if (@($r.pending).Count) {
        if ($curSize -gt 5) { $curSize = [Math]::Max(5, [int][Math]::Floor($curSize / 2)) }
        if ($o -lt $queue.Count) { & $pace $r.maxRetryAfter }
      }
    }
  }
  $script:PimBatchStats.batchSize = $curSize
  # Anything still unanswered (still throttled after the rounds, or a host that does not batch): the single-request
  # path, which owns its own Retry-After/backoff -- so a batch never loses a read the sequential loop would have got.
  for ($i = 0; $i -lt $n; $i++) { if ($null -eq $results[$i]) { $script:PimBatchStats.singles++; $results[$i] = & $single $Paths[$i] } }
  $sw.Stop()
  $st = $script:PimBatchStats
  if ($st.throttled -or $st.serverErrors -or $st.singles -or $sw.Elapsed.TotalSeconds -ge 20) {
    Write-Host ("  [graph-batch] {0} path(s), {1} round-trip(s), {2} throttled (429), {3} server error(s), {4} retry round(s) waiting {5}s (paced {8}s), {6} single fallback(s), batch {9}->{10}, {7:N1}s" -f `
      $n, $st.roundTrips, $st.throttled, $st.serverErrors, $st.retryRounds, $st.waitedSeconds, $st.singles, $sw.Elapsed.TotalSeconds, $st.pacedSeconds, $BatchSize, $st.batchSize) -ForegroundColor DarkGray
  }
  return ,$results
}

function Get-PimArmActiveRoleAssignmentsViaArg {
  <#
    EVERY Azure RBAC role assignment visible to the engine identity, in ONE Azure Resource Graph query
    (POST /providers/Microsoft.ResourceGraph/resources, paged by $skipToken) -- management groups,
    subscriptions, resource groups and resources alike, with the role NAME joined in the same query.
    REST only: no Az module (REQUIREMENTS 67.3). Throws when the query fails, so a caller can say so
    and fall back instead of rendering an empty list as "no assignments".
    Output: { Id; Name; Scope; PrincipalId; PrincipalType; RoleDefinitionId (GUID); RoleDefinitionName }.
    -Stream (100.31 SNAPSHOT-OOM, 2026-10-09): emit each row to the pipeline as its page arrives instead of returning
    the whole set at the end, so a caller that projects rows (`... -Stream | ForEach-Object { }`) holds ONE page of
    raw rows, not every role assignment in the tenant twice.
  #>
  param([int]$PageSize = 1000, [switch]$Stream)
  $kql = @(
    'authorizationresources'
    '| where type =~ ''microsoft.authorization/roleassignments'''
    '| extend roleGuid = tolower(extract(''([^/]+)$'', 1, tostring(properties.roleDefinitionId)))'
    '| project id, name, scope = tostring(properties.scope), principalId = tostring(properties.principalId), principalType = tostring(properties.principalType), roleDefinitionId = tostring(properties.roleDefinitionId), roleGuid'
    '| join kind=leftouter (authorizationresources | where type =~ ''microsoft.authorization/roledefinitions'' | extend roleGuid = tolower(name) | summarize roleName = any(tostring(properties.roleName)) by roleGuid) on roleGuid'
    '| project id, name, scope, principalId, principalType, roleDefinitionId, roleGuid, roleName'
  ) -join ' '
  $out = New-Object System.Collections.Generic.List[object]
  $skipToken = $null
  do {
    $opts = @{ '$top' = $PageSize; resultFormat = 'objectArray' }
    if ($skipToken) { $opts['$skipToken'] = $skipToken }
    $resp = Invoke-PimArm -Method POST -Path '/providers/Microsoft.ResourceGraph/resources' -ApiVersion '2021-03-01' -Body @{ query = $kql; options = $opts }
    foreach ($r in @($resp.data)) {
      if ($null -eq $r) { continue }
      $guid = "$($r.roleGuid)"; if (-not $guid) { $guid = ("$($r.roleDefinitionId)" -split '/')[-1] }
      $o = [pscustomobject]@{
        Id = "$($r.id)"; Name = "$($r.name)"; Scope = "$($r.scope)"; PrincipalId = "$($r.principalId)"; PrincipalType = "$($r.principalType)"
        RoleDefinitionId = $guid; RoleDefinitionName = $(if ("$($r.roleName)".Trim()) { "$($r.roleName)" } else { $null })
      }
      if ($Stream) { $o } else { $out.Add($o) }
    }
    if ($resp -and $resp.PSObject.Properties['data']) { $resp.data = $null }   # the raw page goes as soon as it is projected
    $skipToken = $null
    if ($resp -and $resp.PSObject.Properties['$skipToken'] -and "$($resp.'$skipToken')".Trim()) { $skipToken = "$($resp.'$skipToken')" }
  } while ($skipToken)
  if ($Stream) { return }
  # Unrolled on purpose: `@(Get-PimArmActiveRoleAssignmentsViaArg | ForEach-Object ...)` must see ROWS, not one array.
  return $out.ToArray()
}

function Invoke-PimArm {
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[string]$ApiVersion='2022-04-01',[switch]$All,[hashtable]$Headers=@{})
  $url = if ($Path -match '^https?://') { $Path } else { "https://management.azure.com$Path" }
  if ($url -notmatch 'api-version=') { $url += ($(if ($url -match '\?') {'&'} else {'?'}) + "api-version=$ApiVersion") }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'arm' -All:$All -Headers $Headers
}
function Invoke-PimPowerBI {
  # PIM 100.142: -MaxRetry passes through, so the admin-api client (Invoke-PimPowerBiAdminRequest, PIM-WorkloadConnectors.ps1)
  # can own the 429 handling (the admin api allows 200 requests per hour). The default (5) is unchanged for every other caller.
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[switch]$All,[hashtable]$Headers=@{},[int]$MaxRetry=5)
  $url = if ($Path -match '^https?://') { $Path } else { "https://api.powerbi.com/v1.0/myorg$Path" }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'powerbi' -All:$All -Headers $Headers -MaxRetry $MaxRetry
}

# ---- Exchange Online (app-only, pure REST, NO ExchangeOnlineManagement) ----
# The EXO V3 PowerShell module's "REST-backed cmdlets" are thin wrappers around
# the Exchange admin REST endpoint:
#   POST https://outlook.office365.com/adminapi/beta/<tenant>/InvokeCommand
#   body { CmdletInput: { CmdletName: '<Verb-Noun>', Parameters: { ... } } }
# authenticated with an app-only token for the https://outlook.office365.com
# audience (the same Exchange.ManageAsApp consent the module needs). Calling
# this endpoint directly means the engine sets mailbox forwarding etc. with the
# engine SPN + certificate over PIM-Rest -- no module to Install-Module, no EXO
# V3 runspace-state bug, PS 5.1-safe. Anti-affinity routing (X-AnchorMailbox /
# Prefer) is unnecessary for tenant-admin cmdlets against the beta endpoint.
#
# NOTE on feasibility: NOT every EXO cmdlet is reachable this way -- some are
# session-bound or stream large result sets the InvokeCommand shape doesn't
# return cleanly. The engine's ONLY runtime EXO need is Set-Mailbox mail
# forwarding, which is a simple parameterized cmdlet and works over this path.
# Connect-ExchangeOnline itself becomes a no-op (token-per-call, no session).
function Get-PimExoTenantSegment {
  # The InvokeCommand path takes the tenant's *initial* domain or tenant GUID.
  param([string]$TenantId)
  $t = if ($TenantId) { $TenantId } elseif ($global:PIM_ExoOrganization) { $global:PIM_ExoOrganization } elseif ($global:PIM_TenantId) { $global:PIM_TenantId } else { Get-PimTenantId }
  if (-not $t) { throw "Invoke-PimExoCmdlet: no tenant/organization. Set -Organization, `$global:PIM_ExoOrganization (initial .onmicrosoft.com domain) or `$global:PIM_TenantId." }
  return $t
}
function Invoke-PimExoCmdlet {
  <#
    Run a single Exchange Online admin cmdlet app-only over REST.
      Invoke-PimExoCmdlet -CmdletName 'Set-Mailbox' -Parameters @{ Identity='u@x'; ForwardingSmtpAddress='a@b'; DeliverToMailboxAndForward=$false }
    Returns the cmdlet's .value payload (array) or the raw response.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][string]$CmdletName,
    [hashtable]$Parameters = @{},
    [string]$Organization,
    [int]$MaxRetry = 5
  )
  $seg = Get-PimExoTenantSegment -TenantId $Organization
  $url = "https://outlook.office365.com/adminapi/beta/$seg/InvokeCommand"
  $body = @{ CmdletInput = @{ CmdletName = $CmdletName; Parameters = $Parameters } }
  $resp = Invoke-PimRest -Method POST -Url $url -Body $body -Resource 'exo' -MaxRetry $MaxRetry
  if ($null -ne $resp -and ($resp.PSObject.Properties.Name -contains 'value')) { return $resp.value }
  return $resp
}
function Test-PimMailForwardAddressIsReal {
  <#
    Shared sentinel predicate -- the engine apply path and the Manager validator
    (tools/pim-manager/_validator.ps1, PIM-DOMAIN-001) MUST agree on what counts
    as a real forwarding address. The Account-Definitions schema reuses the
    literal string 'FALSE' (and blanks / 'no' / '0' / 'none' / 'n/a') to mean
    "no forwarding address", so those values are NOT addresses and must never be
    forwarded to. Returns $true only for something shaped like an email address.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Value)
  $s = ([string]$Value).Trim()
  if (-not $s) { return $false }
  switch ($s.ToUpperInvariant()) {
    'FALSE' { return $false }
    'NO'    { return $false }
    '0'     { return $false }
    'NONE'  { return $false }
    'N/A'   { return $false }
    default { return ($s -match '^[^@\s]+@[^@\s]+\.[^@\s]+$') }
  }
}

function Get-PimAdminMailRecipient {
  <#
    THE ONE RECIPIENT RULE for mail PIM sends about an admin account (new-admin, tap-delivery).
    Shared by the engine (PIM-EngineProviders.ps1) and the Manager (Get-PimAdminTapRecipient), so
    the screen's "Sends to" is exactly the address the engine mails.

      ForwardMailsToContact = TRUE  AND  MailForwardAddress is a real address  -> MailForwardAddress
      else the admin's SPONSOR DEPARTMENT's Owners                             -> all of them
      else ManagerEmail, if it is a real address                               -> LEGACY ONLY
      else                                                                     -> ''  (caller refuses)

    🔑 The rule, and the reason for each step, live on Get-PimAdminMailRecipientPlan below -- this is
    only the string-returning wrapper. Read that comment before changing anything here. In particular
    the sponsor is a DEPARTMENT, not a person (operator, 2026-09-16), and ManagerEmail survives solely
    so existing data keeps working; it is reported as 'manager-legacy' so callers can say "move this
    to the department".
    🔑 Operator, 2026-09-12 ("Both"): MailForwardAddress is the admin OWNER's office user. An admin
    account has no mailbox of its own, so PIM's own mail goes to that office user; and where the admin
    account DOES have a mailbox, the engine also sets Exchange forwarding to it (gated, see
    Invoke-PimAdminMailboxForwarding). The columns were retired 2026-08-12 and are un-retired with
    this meaning.
    🪤 An address that is not an address ('FALSE'/'true' -- measured as live v1 data on internal) is
    NOT a recipient. Test-PimMailForwardAddressIsReal is the shared predicate; 'true' fails its
    address shape and is rejected here explicitly as well.
    🪤 This wrapper returns only the FIRST recipient. Anything that mails a department (which can have
    several owners) must call Get-PimAdminMailRecipientPlan and use .recipients.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Row, [hashtable]$DepartmentOwners)
  $plan = if ($PSBoundParameters.ContainsKey('DepartmentOwners')) { Get-PimAdminMailRecipientPlan -Row $Row -DepartmentOwners $DepartmentOwners }
          else { Get-PimAdminMailRecipientPlan -Row $Row }
  return "$($plan.recipient)"
}

function Split-PimMailRecipients {
  # PURE. A recipient list as the model writes it (pipe-joined UPNs per the Manager UX; ';' and ',' accepted too) --
  # the SAME parsing the group-owner path uses (Split-PimOwners), so an admin's department owners and a group's owners
  # can never be read differently.
  param([AllowNull()][string]$Raw)
  @("$Raw" -split '[|;,]' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
}

function Get-PimAdminMailRecipientPlan {
  <#
    🔑 71.19 -- THE SPONSOR IS A DEPARTMENT, NOT A PERSON (operator, 2026-09-16: *"the logic is that an admin is linked
    to a dept (sponsor) and the dept has owners ... change the code, as i think logic is wrong"*; REQUIREMENTS §62:
    *"we dont add a manager on the person"*, *"whoever is the actual manager of the dept gets the emails, approvals
    etc"*, *"otherwise you are vulnerable for org changes"*).

    Who receives PIM's mail about an admin account (new-admin notice, TAP delivery), in order:

      1. ForwardMailsToContact = TRUE AND MailForwardAddress is a real address
         -> that address. The deliberate PER-ADMIN OVERRIDE (operator 2026-09-12 "Both": the admin owner's office
            user). Kept because it is an explicit statement on the row, not a person-as-manager guess.
      2. the admin's SPONSOR DEPARTMENT's owners: Account-Definitions-Admins.Department -> the
         PIM-Definitions-Departments row for that department -> its Owners (pipe/;/,-joined UPNs)
         -> ALL of them. This is the rule.
      3. ManagerEmail, if it is a real address -> LEGACY ONLY, so existing data keeps working. It is reported as
         'manager-legacy' so the validator, the Manager and the readiness check can say "move this to the department".
      4. nothing -> '' and a reason that names the admin, its department and what to set.

    The department index is INJECTED (-DepartmentOwners: department name in lower case -> owners string) because this
    file is the transport layer and must not read the store; the engine passes Get-PimDepartmentOwnerIndex, the Manager
    and the validator pass their own. Without it, step 2 is skipped and the reason says the index was not supplied --
    never silently "no department".

    Returns @{ recipients = @(all); recipient = <first>; source = forward|department|manager-legacy|none;
               department; reason; legacy = [bool] }.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Row, [hashtable]$DepartmentOwners = $null)
  $out = [ordered]@{ recipients = @(); recipient = ''; source = 'none'; department = ''; reason = ''; legacy = $false }
  if ($null -eq $Row) { $out['reason'] = 'no admin row'; return $out }
  $get = {
    param($name)
    if ($Row -is [System.Collections.IDictionary]) { return "$($Row[$name])".Trim() }
    $p = $Row.PSObject.Properties[$name]
    if ($p) { return "$($p.Value)".Trim() }
    return ''
  }
  $isAddr = { param($v) ("$v" -notmatch '(?i)^(true|yes|1)$') -and (Test-PimMailForwardAddressIsReal -Value $v) }
  $who = & $get 'UserPrincipalName'; if (-not $who) { $who = & $get 'UserName' }
  $dept = & $get 'Department'
  # When the caller did not inject one, use the engine's own index if this process has it loaded (the engine and the
  # Manager both do). Wrapped: a store read that fails must leave the reason "not supplied", never pretend "no owners".
  if ($null -eq $DepartmentOwners -and (Get-Command Get-PimDepartmentOwnerIndex -ErrorAction SilentlyContinue)) {
    try { $DepartmentOwners = Get-PimDepartmentOwnerIndex } catch { $DepartmentOwners = $null }
  }
  $out['department'] = $dept

  $fwdOn = ((& $get 'ForwardMailsToContact') -match '(?i)^(true|yes|1)$')
  $fwd   = & $get 'MailForwardAddress'
  if ($fwdOn -and (& $isAddr $fwd)) {
    $out['recipients'] = @($fwd); $out['recipient'] = $fwd; $out['source'] = 'forward'
    $out['reason'] = "per-admin override: ForwardMailsToContact=TRUE + MailForwardAddress on $who"
    return $out
  }

  if ($dept) {
    if ($null -eq $DepartmentOwners) {
      $out['reason'] = "the department owner index was not supplied to this call, so '$dept' could not be resolved (load the store / pass -DepartmentOwners)"
    } else {
      $key = $dept.ToLowerInvariant()
      if ($DepartmentOwners.ContainsKey($key)) {
        $owners = @(Split-PimMailRecipients ("$($DepartmentOwners[$key])")) | Where-Object { & $isAddr $_ }
        if (@($owners).Count) {
          $out['recipients'] = @($owners); $out['recipient'] = @($owners)[0]; $out['source'] = 'department'
          $out['reason'] = "sponsor department '$dept' owner(s): $(@($owners) -join ', ')"
          return $out
        }
        $out['reason'] = "the sponsor department '$dept' of $who has no usable Owners -- set Owners on that department (PIM-Definitions-Departments)"
      } else {
        $out['reason'] = "$who names department '$dept', but there is no PIM-Definitions-Departments row for it -- add the department (with Owners), or correct the admin's Department"
      }
    }
  } else {
    $out['reason'] = "$who has no Department -- an admin's mail goes to its SPONSOR DEPARTMENT's owners, so set the admin's Department and give that department Owners"
  }

  $mgr = & $get 'ManagerEmail'
  if (& $isAddr $mgr) {
    $out['recipients'] = @($mgr); $out['recipient'] = $mgr; $out['source'] = 'manager-legacy'; $out['legacy'] = $true
    $out['reason'] = "LEGACY: using ManagerEmail ($mgr) on $who. The rule is the sponsor department's owners -- $($out['reason'])"
    return $out
  }
  # 5. 2026-09-21 (operator: "i cannot set tap on managing tenant either" / "we must also get email from managed tenants when account is
  #    created/replicated down"): with no override, no department owner and no legacy manager, the mail about this admin
  #    (new-admin notice, TAP) goes to THIS tenant's ALERT RECIPIENTS (PIM_AlertRecipient + Manager > Alerting) -- the
  #    people who run the environment. Before, there was nobody to send to, so no TAP could be issued at all and a
  #    replicated admin arrived in a managed tenant without anyone being told. Reported as 'alert-recipients' so the screens
  #    still say "set a sponsor department" for the proper route.
  $alert = @()
  try {
    if (Get-Command Get-PimSafetyAlertRecipients -ErrorAction SilentlyContinue) { $alert = @(Get-PimSafetyAlertRecipients) }
    elseif (Get-Command Get-PimAlertingConfig -ErrorAction SilentlyContinue) { $alert = @((Get-PimAlertingConfig).recipients) }
  } catch { $alert = @() }
  $alert = @($alert | ForEach-Object { "$_".Trim() } | Where-Object { & $isAddr $_ } | Select-Object -Unique)
  if ($alert.Count) {
    $out['recipients'] = @($alert); $out['recipient'] = $alert[0]; $out['source'] = 'alert-recipients'
    $out['reason'] = "no sponsor department owner for $who -- sent to this tenant's alert recipients ($($alert -join ', ')). $($out['reason'])"
    return $out
  }
  return $out
}

function Test-PimAdminMailboxForwardingEnabled {
  <#
    Opt-in gate for setting Exchange mailbox forwarding on admin accounts. DEFAULT OFF, so rolling an
    image changes nothing until an operator turns it on: it needs an Exchange app permission
    (Exchange.ManageAsApp + an EXO role) whose grant model is still unresolved (§65.11).
    $global:PIM_AdminMailboxForwarding first, then $env:PIM_AdminMailboxForwarding (SEC-07 order,
    so a container-app setting is honoured). Only an explicit true/1/yes enables it.
  #>
  [CmdletBinding()]
  param([object]$Override = $null)
  $v = if ($null -ne $Override) { $Override }
       elseif (Get-Command Get-PimFeatureSetting -ErrorAction SilentlyContinue) { Get-PimFeatureSetting -Name 'AdminMailboxForwarding' }   # PIM 100.121: process -> environment -> store -> off
       elseif ($null -ne $global:PIM_AdminMailboxForwarding -and "$($global:PIM_AdminMailboxForwarding)".Trim()) { $global:PIM_AdminMailboxForwarding }
       else { $env:PIM_AdminMailboxForwarding }
  return ("$v".Trim() -match '(?i)^(true|1|yes|on)$')
}

function Invoke-PimAdminMailboxForwarding {
  <#
    BEST-EFFORT, INERT-SAFE mailbox forwarding for ONE admin account. Never throws -- an admin
    apply must not fail because forwarding could not be set.

      gate OFF                                  -> 'disabled'   (no call at all)
      account has no mailbox                    -> 'no-mailbox' (Verbose only -- the NORMAL case:
                                                                 admin accounts usually hold no licence)
      flag TRUE + real address                  -> forward to it, DeliverToMailboxAndForward=$false
      flag not TRUE, mailbox currently forwards -> clear it
      flag not TRUE, nothing forwarded          -> 'nochange'
      401/403 from Graph or EXO                 -> ONE warning per run naming the permission, 'forbidden'

    -GraphInvoker / -ExoInvoker exist for offline tests; production uses Invoke-PimGraph and
    Set-PimMailboxForwarding / Invoke-PimExoCmdlet.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][AllowNull()][object]$Row,
    [Parameter(Mandatory)][string]$UserPrincipalName,
    [string]$UserId,
    [object]$Enabled = $null,
    [scriptblock]$GraphInvoker,
    [scriptblock]$ExoInvoker
  )
  try {
    if (-not (Test-PimAdminMailboxForwardingEnabled -Override $Enabled)) { return 'disabled' }
    $id = if ("$UserId".Trim()) { "$UserId".Trim() } else { $UserPrincipalName }
    $isForbidden = { param($err) ("$err" -match '(?i)\b(401|403)\b|Forbidden|Unauthorized|AccessDenied|Authorization_RequestDenied') }
    $warnOnce = {
      param($what)
      if (-not $script:PimAdminFwdForbiddenWarned) {
        $script:PimAdminFwdForbiddenWarned = $true
        Write-Warning ("  [AdminForwarding] $what was refused (401/403). Mailbox forwarding needs the Exchange " +
          "application permission Exchange.ManageAsApp plus an Exchange role (e.g. Mail Recipients) for the identity " +
          "the engine runs as. Skipping forwarding for every admin this run; nothing else is affected.")
      }
    }
    # 1. Does the account have a mailbox? (cheap: one GET, and the answer is usually "no")
    try {
      $null = if ($GraphInvoker) { & $GraphInvoker 'GET' "/users/$id/mailboxSettings" }
              else { Invoke-PimGraph -Method GET -Path "/users/$id/mailboxSettings" }
    } catch {
      $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
      if ($m -match '(?i)MailboxNotEnabledForRESTAPI|MailboxNotFound|ResourceNotFound|\b404\b|not found') {
        Write-Verbose "  [AdminForwarding] $UserPrincipalName has no mailbox -- nothing to forward."
        return 'no-mailbox'
      }
      if (& $isForbidden $m) { & $warnOnce 'Reading mailboxSettings'; return 'forbidden' }
      Write-Verbose "  [AdminForwarding] $UserPrincipalName mailbox probe failed: $m"
      return 'error'
    }
    # 2. Apply or clear.
    $flagOn = ("$(if ($Row -is [System.Collections.IDictionary]) { $Row['ForwardMailsToContact'] } else { $Row.ForwardMailsToContact })".Trim() -match '(?i)^(true|yes|1)$')
    $addr   = "$(if ($Row -is [System.Collections.IDictionary]) { $Row['MailForwardAddress'] } else { $Row.MailForwardAddress })".Trim()
    $exo = {
      param($cmd, $params)
      if ($ExoInvoker) { return (& $ExoInvoker $cmd $params) }
      return (Invoke-PimExoCmdlet -CmdletName $cmd -Parameters $params)
    }
    try {
      if ($flagOn -and (Test-PimMailForwardAddressIsReal -Value $addr) -and ($addr -notmatch '(?i)^(true|yes|1)$')) {
        & $exo 'Set-Mailbox' @{ Identity = $UserPrincipalName; ForwardingSmtpAddress = $addr; DeliverToMailboxAndForward = $false } | Out-Null
        return 'forwarded'
      }
      $cur = @(& $exo 'Get-Mailbox' @{ Identity = $UserPrincipalName })
      $curFwd = if ($cur.Count) { "$($cur[0].ForwardingSmtpAddress)".Trim() } else { '' }
      if (-not $curFwd) { return 'nochange' }
      & $exo 'Set-Mailbox' @{ Identity = $UserPrincipalName; ForwardingSmtpAddress = $null; DeliverToMailboxAndForward = $false } | Out-Null
      return 'cleared'
    } catch {
      $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
      if (& $isForbidden $m) { & $warnOnce 'Set-Mailbox'; return 'forbidden' }
      Write-Warning "  [AdminForwarding] $UserPrincipalName -- forwarding could not be set: $m (the admin account itself was applied)."
      return 'error'
    }
  } catch {
    Write-Verbose "  [AdminForwarding] $UserPrincipalName -- unexpected: $($_.Exception.Message)"
    return 'error'
  }
}

function Set-PimMailboxForwarding {
  <#
    Pure-REST equivalent of the engine's only runtime EXO call:
      Set-Mailbox -Identity <upn> -ForwardingSmtpAddress <smtp> -DeliverToMailboxAndForward:$false
    Pass -ForwardingSmtpAddress '' to CLEAR forwarding.

    Safety net: a 'FALSE'/sentinel address is treated as "no address" (clears
    forwarding) so the engine never forwards mail to the literal string 'FALSE'
    even if a caller forgets the upstream guard. Aligns with
    Test-PimMailForwardAddressIsReal in the validator.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][string]$Identity,
    [string]$ForwardingSmtpAddress,
    [bool]$DeliverToMailboxAndForward = $false,
    [string]$Organization
  )
  $p = @{ Identity = $Identity; DeliverToMailboxAndForward = $DeliverToMailboxAndForward }
  # EXO accepts a null to clear forwarding; an empty string is rejected. A
  # sentinel ('FALSE'/'no'/'0'/...) is NOT a real address -> clear instead.
  if (-not (Test-PimMailForwardAddressIsReal -Value $ForwardingSmtpAddress)) { $p['ForwardingSmtpAddress'] = $null }
  else { $p['ForwardingSmtpAddress'] = $ForwardingSmtpAddress }
  Invoke-PimExoCmdlet -CmdletName 'Set-Mailbox' -Parameters $p -Organization $Organization | Out-Null
}

# ===== END inlined helper: ..\..\engine\_shared\PIM-Rest.ps1 =====
# ===== BEGIN inlined helper: _PimSignedIn.ps1 =====
<#
.SYNOPSIS
    71.33 -- the SIGNED-IN (interactive) identity for the one-shot MSP build and the setup steps it runs.

.DESCRIPTION
    Operator 2026-09-17: "I thought I could just do interactive login to deploy." A customer deploys by signing in
    as a human administrator; certificates are the MSP management host's automation pattern only. So every step the
    build runs inside ONE tenant accepts -UseSignedInAccount (or, where the script already had that convention, simply
    no credential) and then authenticates through the ONE sign-in rule (framework 12.17, REQ 100.42): the Invardia
    Support session open in this window (Use-PimSupportAppRestSession / Get-InvardiaSupportToken), otherwise the
    person's own browser sign-in (auth code + PKCE, never device code), registered into PIM-Rest as
    $global:PIM_TokenProvider. No command-line tool, no module, no certificate, no secret, nothing written to disk by
    this code, and no token ever printed or logged.

    WHAT IS ASSERTED BEFORE ANYTHING IS USED (a wrong default context on a multi-tenant machine is a real trap):
      * the signed-in principal is a USER (an application is refused -- that is the certificate mode's job, and a
        signed-in SPN would silently change who the audit trail names) -- or exactly the Invardia Support app;
      * its tenant equals the build config's tenantId, and the subscription is the one named explicitly and visible;
      * every token minted from it (ARM, SQL) is decoded and its tenant and user-ness checked;
      * no environment variable is set that would make a token call quietly authenticate as somebody else
        (AZURE_CLIENT_SECRET, PIM_CERT_THUMBPRINT, a managed identity endpoint ...).

    SQL: Azure SQL here is Entra-only, so the signed-in user needs database rights -- by being a MEMBER of the SQL admin
    group (grp-pim-sql-admins) that is the server's Entra admin. Invoke-PimSignedInSqlAdminMembership adds the user as a
    member (members-only: it never creates the group and never moves the admin).
    TRAP: an Entra token carries group membership as of when it was issued, and a token is reused for up to about an
    hour. A user added to the group in THIS run may be refused by SQL until their token refreshes -- the helper says so.

    Pure parts are offline-tested in tests/Test-PimMspBuild.ps1 (section S).
#>

$script:PimSignedInGuid = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
# Environment variables that make a token call authenticate as SOMEBODY ELSE than the signed-in user.
$script:PimSignedInConflictVars = @('AZURE_CLIENT_ID', 'AZURE_CLIENT_SECRET', 'AZURE_CLIENT_CERTIFICATE_PATH', 'AZURE_FEDERATED_TOKEN_FILE',
                                    'PIM_CERT_THUMBPRINT', 'IDENTITY_ENDPOINT', 'MSI_ENDPOINT')

function ConvertFrom-PimJwtClaims {
    # PURE. The claims of a JWT (never validates the signature -- this is only used to ASSERT who a token is for).
    param([string]$Token)
    try {
        $seg = "$Token".Split('.')[1].Replace('-', '+').Replace('_', '/')
        while ($seg.Length % 4) { $seg += '=' }
        return ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($seg)) | ConvertFrom-Json)
    } catch { return $null }
}

function Get-PimSupportAppSession {
    <#
      PURE given -Environment (name -> value; default: this process). The Invardia Support app session that an older
      Invardia connect script announced in THIS shell through environment variables (framework 4.1a), or $null. It is
      recognised only when the connect script's private profile folder IS the active one (INVARDIA_SUPPORT_AZCONFIG ==
      AZURE_CONFIG_DIR) -- a service principal signed in any other way is never treated as the support app. Used only to
      ACCEPT that app's token; the token itself always comes from PIM-Rest's one client.
      Returns @{ tenantId; subscriptions[]; environment } or $null.
    #>
    param([hashtable]$Environment)
    $get = { param($n) if ($Environment) { "$($Environment[$n])" } else { "$([Environment]::GetEnvironmentVariable($n))" } }
    $dir = "$(& $get 'INVARDIA_SUPPORT_AZCONFIG')".Trim(); $cur = "$(& $get 'AZURE_CONFIG_DIR')".Trim()
    if (-not $dir -or -not $cur -or $dir.TrimEnd('\', '/') -ne $cur.TrimEnd('\', '/')) { return $null }
    $tid = "$(& $get 'INVARDIA_SUPPORT_TENANT')".Trim().ToLowerInvariant()
    if ($tid -notmatch $script:PimSignedInGuid) { return $null }
    $subs = @("$(& $get 'INVARDIA_SUPPORT_SUBSCRIPTIONS')" -split '[,;\s]+' | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ -match $script:PimSignedInGuid })
    return @{ tenantId = $tid; subscriptions = $subs; environment = "$(& $get 'INVARDIA_SUPPORT_ENVIRONMENT')".Trim() }
}

function Test-PimSignedInToken {
    <#
      PURE. Assert a token belongs to a signed-in USER of -TenantId. Returns @{ ok; reason; objectId; userName; tenantId }.
      An application token (idtyp=app, or no user claims) is refused: that is a different principal wearing the same call.
    #>
    # -AllowedAppId: the Invardia Support app's appId (from Test-PimSignedInAccount); an application token is accepted
    # ONLY when its appid is exactly that app.
    param([string]$Token, [string]$TenantId, [string]$AllowedAppId = '')
    $c = ConvertFrom-PimJwtClaims -Token $Token
    if (-not $c) { return @{ ok = $false; reason = 'the token could not be decoded' } }
    $tid = "$($c.tid)".Trim().ToLowerInvariant()
    if ($tid -ne "$TenantId".Trim().ToLowerInvariant()) { return @{ ok = $false; reason = "the token is for tenant '$tid', not '$TenantId' -- REFUSING" } }
    $upn = "$(if ($c.upn) { $c.upn } elseif ($c.unique_name) { $c.unique_name } elseif ($c.preferred_username) { $c.preferred_username } else { '' })".Trim()
    $idtyp = "$($c.idtyp)".Trim().ToLowerInvariant()
    $appid = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
    if ("$AllowedAppId".Trim() -and $appid -eq "$AllowedAppId".Trim().ToLowerInvariant() -and -not $upn) {
        if ("$($c.oid)".Trim() -notmatch $script:PimSignedInGuid) { return @{ ok = $false; reason = 'the support app token carries no object id' } }
        return @{ ok = $true; reason = ''; objectId = "$($c.oid)".Trim().ToLowerInvariant(); userName = "Invardia Support app ($appid)"; tenantId = $tid; supportApp = $true }
    }
    if ($idtyp -eq 'app' -or (-not $upn -and $idtyp -ne 'user')) {
        return @{ ok = $false; reason = "the token is an APPLICATION token (appid '$($c.appid)'), not the signed-in user's -- REFUSING" }
    }
    if ("$($c.oid)".Trim() -notmatch $script:PimSignedInGuid) { return @{ ok = $false; reason = 'the token carries no user object id' } }
    return @{ ok = $true; reason = ''; objectId = "$($c.oid)".Trim().ToLowerInvariant(); userName = $upn; tenantId = $tid }
}

function Test-PimCloudShell {
    # PURE given -Environment. Azure Cloud Shell sets AZUREPS_HOST_ENVIRONMENT=cloud-shell/<ver> and ACC_CLOUD; there the
    # MSI_ENDPOINT / IDENTITY_ENDPOINT serve the SIGNED-IN USER's token (Cloud Shell's own token broker), not a machine
    # identity -- so they are no conflict there (§95.2 Cloud Shell blocker 2, guided install 2026-10-03).
    param([hashtable]$Environment)
    $get = { param($n) if ($Environment) { "$($Environment[$n])" } else { "$([Environment]::GetEnvironmentVariable($n))" } }
    return ((& $get 'AZUREPS_HOST_ENVIRONMENT') -match '^(?i)cloud-shell') -or [bool]"$(& $get 'ACC_CLOUD')".Trim()
}

function Get-PimSignedInEnvironmentConflicts {
    # PURE given -Environment (a hashtable name -> value); by default reads this process. The names that are set.
    # In Azure Cloud Shell MSI_ENDPOINT / IDENTITY_ENDPOINT are the user's own token broker and are not counted.
    param([hashtable]$Environment)
    $cloudShell = Test-PimCloudShell -Environment $Environment
    $out = @()
    foreach ($n in $script:PimSignedInConflictVars) {
        if ($cloudShell -and $n -in 'MSI_ENDPOINT', 'IDENTITY_ENDPOINT') { continue }
        $v = if ($Environment) { $Environment[$n] } else { [Environment]::GetEnvironmentVariable($n) }
        if ("$v".Trim()) { $out += $n }
    }
    return @($out)
}

function Clear-PimSignedInMachineIdentity {
    <#
      Azure Arc and the Azure VM agent set IDENTITY_ENDPOINT / MSI_ENDPOINT (+ IMDS_ENDPOINT / IDENTITY_HEADER) MACHINE-WIDE,
      so on a customer's Arc-joined jump host every signed-in script used to stop with "IDENTITY_ENDPOINT is set in this
      session" (a customer, 2026-10-21) and the admin had to clear them by hand. They name the MACHINE's identity, never the person:
      this script clears them for ITS OWN PROCESS only -- the machine and its agent are untouched -- and says so in one line.
      Not in Azure Cloud Shell, where they are the signed-in user's own token broker. Returns the names it cleared.
    #>
    param([hashtable]$Environment)
    if (Test-PimCloudShell -Environment $Environment) { return @() }
    $names = @('IDENTITY_ENDPOINT', 'MSI_ENDPOINT', 'IMDS_ENDPOINT', 'IDENTITY_HEADER', 'MSI_SECRET')
    $set = @($names | Where-Object { "$(if ($Environment) { $Environment[$_] } else { [Environment]::GetEnvironmentVariable($_) })".Trim() })
    if (-not $set.Count) { return @() }
    foreach ($n in $set) { if ($Environment) { $Environment.Remove($n) } else { [Environment]::SetEnvironmentVariable($n, $null, 'Process') } }
    Write-Host "  note: this machine's own identity ($($set -join ', '), set by Azure Arc or the Azure VM agent) is ignored for this run -- you sign in as yourself; the machine is not changed." -ForegroundColor DarkGray
    return @($set)
}

function Get-PimSignedInConflictHint {
    # PURE. How to clear the named variables for THIS session only (§73.9: on an Azure Arc / Azure VM host
    # IDENTITY_ENDPOINT is set machine-wide, and an operator had to be told how to clear it).
    param([string[]]$Names)
    $n = @($Names | Where-Object { "$_".Trim() })
    if (-not $n.Count) { return '' }
    $cmd = ($n | ForEach-Object { "`$env:$_ = `$null" }) -join '; '
    $arc = if ($n -contains 'IDENTITY_ENDPOINT' -or $n -contains 'MSI_ENDPOINT') {
        ' IDENTITY_ENDPOINT / MSI_ENDPOINT are set machine-wide by Azure Arc or an Azure VM agent: clearing them in this window affects this window only, never the machine or the agent.'
    } else { '' }
    return "Clear them for this session only, then re-run in the same window: $cmd.$arc Or use the certificate mode."
}

function Use-PimSupportAppRestSession {
    <#
      100.41 / framework 4.1a -- the Invardia Support app's REST session ($global:InvardiaSupportState, set by
      Connect-InvardiaSupport.ps1 -Environment <handle>) for -TenantId (+ an allowed -SubscriptionId): point PIM-Rest's ONE token
      client at it (client credentials with the app's secret -- the one agreed support method). Returns the app id
      (lowercase) or '' when no such session covers this tenant + subscription. Nothing is printed; the secret only moves
      into PIM-Rest's process-local global. -State is the test seam (default: the session in this shell).
    #>
    param([Parameter(Mandatory)][string]$TenantId, [string]$SubscriptionId, [object]$State)
    $s = if ($PSBoundParameters.ContainsKey('State')) { $State } else { $global:InvardiaSupportState }
    if (-not ($s -is [hashtable]) -or -not $s.Secret -or "$($s.AppId)" -notmatch $script:PimSignedInGuid) { return '' }
    if ("$($s.TenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return '' }
    $subs = @(@($s.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    if ("$SubscriptionId".Trim() -and -not ($subs -contains "$SubscriptionId".Trim().ToLowerInvariant())) { return '' }
    # Owner token rule (2026-10-09): tools get TOKENS from Get-InvardiaSupportToken -- the Support app's secret NEVER leaves
    # the support session. So PIM-Rest is pointed at the session's token function (Set-PimSignedInGlobals registers
    # Get-PimSignedInToken as $global:PIM_TokenProvider), never at a copy of the secret.
    if (-not $PSBoundParameters.ContainsKey('State') -and -not (Get-Command Get-InvardiaSupportToken -ErrorAction SilentlyContinue)) { return '' }
    Set-PimSignedInGlobals -TenantId "$TenantId".Trim().ToLowerInvariant()
    foreach ($n in 'PIM_ClientSecret', 'PIM_CertThumbprint', 'PIM_UseManagedIdentity', 'PIM_Interactive', 'PIM_InteractiveFallback') { Set-Variable -Scope Global -Name $n -Value $null -WhatIf:$false }
    $global:PIM_NoManagedIdentity = $true
    return "$($s.AppId)".Trim().ToLowerInvariant()
}

function Get-PimSignedInIdentity {
    <#
      Read and ASSERT the signed-in identity for one tenant + subscription. Returns @{ ok; reason; userName; objectId;
      tenantId; subscriptionId }. The ARM token is minted only to read the user's object id and is then discarded.
      100.41 / 100.42 (NO-AZ, framework 12.17): over REST only -- the token comes from PIM-Rest's ONE client (the Invardia
      Support app's REST session when one covers this tenant, else the person's own browser sign-in), its claims are
      asserted, and the subscription is read over ARM to prove it is visible and in -TenantId. There is no second path.
      -Token / -Arm are the REST test seams: { param($Resource, $TenantId) <jwt> } and { param($Path) <ARM object> }.
    #>
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$SubscriptionId, [scriptblock]$Token, [scriptblock]$Arm)
    [void](Clear-PimSignedInMachineIdentity); $conf = @(Get-PimSignedInEnvironmentConflicts)
    if ($conf.Count) {
        return @{ ok = $false; reason = ("REFUSED: $($conf -join ', ') $(if ($conf.Count -eq 1) { 'is' } else { 'are' }) set in this session -- a token call would authenticate as " +
                 'that identity instead of the signed-in user. ' + (Get-PimSignedInConflictHint -Names $conf)) }
    }
    return (Get-PimSignedInIdentityRest -TenantId $TenantId -SubscriptionId $SubscriptionId -Token $Token -Arm $Arm)
}

function Get-PimSignedInToken {
    <#
      REQ 100.42 / framework 12.17 (owner 2026-10-09: "modern single connect only"; owner token rule: tools get TOKENS from
      Get-InvardiaSupportToken). THE token source of a signed-in setup run, registered into PIM-Rest by
      Set-PimSignedInGlobals ($global:PIM_TokenProvider). No command-line tool, no module:
        * the Invardia Support-app session is open in this shell (Get-InvardiaSupportToken exists) -> its token;
        * otherwise the signed-in person -> Get-PimInteractiveToken (browser, auth-code + PKCE; never device code).
      Returns the token string (Support app) or PIM-Rest's @{ token; expiresUtc } (interactive). PIM-Rest verifies the tid.
    #>
    # STALE SUPPORT SESSION (framework 0 "Installer rules", item 2; 2026-11-03): Get-InvardiaSupportToken
    # stays DEFINED in a PowerShell window after an earlier run's support session, also when its token can no longer be minted
    # (the session expired, or it was for another tenant). The install then failed with "could not sign in" instead of signing
    # the person in. Now: when the support-token call THROWS and there is no live session for this tenant (+ subscription)
    # (Test-PimSupportSessionCovers -- the same test Use-PimSupportAppRestSession makes) and a person can sign in here
    # ($global:PIM_InteractiveFallback), the run falls back to the browser
    # sign-in, says so in one line, and stays there. NEVER two identities in one run: a run that got a support token keeps
    # it (a later failure is an error, never a quiet switch to the person), and a run that fell back never asks the support
    # session again. Set-PimSignedInGlobals starts each run afresh.
    param([Parameter(Mandatory)][string]$Audience, [string]$TenantId)
    if ("$script:PimSignedInSource" -ne 'browser' -and (Get-Command Get-InvardiaSupportToken -ErrorAction SilentlyContinue)) {
        try {
            $st = Get-InvardiaSupportToken -Resource ("$Audience".TrimEnd('/'))
            $script:PimSignedInSource = 'support'
            return $st
        } catch {
            $tenantNow = if ("$TenantId".Trim()) { "$TenantId".Trim() } else { "$global:PIM_TenantId".Trim() }
            # the same test as Test-PimSupportSessionCovers, written out here: this function is also registered on its own as
            # PIM-Rest's token source ($global:PIM_TokenProvider) and must not depend on another function of this file
            $ss = $global:InvardiaSupportState; $live = $false
            if ($ss -is [hashtable] -and $ss.Secret -and "$($ss.AppId)" -match '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' -and
                $tenantNow -and "$($ss.TenantId)".Trim().ToLowerInvariant() -eq $tenantNow.ToLowerInvariant()) {
                $ssSubs = @(@($ss.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
                $live = (-not "$script:PimSignedInSubscriptionId".Trim()) -or ($ssSubs -contains "$script:PimSignedInSubscriptionId".Trim().ToLowerInvariant())
            }
            # ...and only where a person can sign in (PIM-Rest's own flag, set by Get-PimSignedInIdentityRest): an unattended
            # run keeps the error instead of waiting on a browser nobody sees
            if ("$script:PimSignedInSource" -eq 'support' -or $live -or -not $global:PIM_InteractiveFallback) { throw }
            Write-Host 'The Invardia Support session left in this PowerShell window can no longer sign in -- signing you in in the browser instead.' -ForegroundColor Yellow
            $script:PimSignedInSource = 'browser'
        }
    }
    if (-not (Get-Command Get-PimInteractiveToken -ErrorAction SilentlyContinue)) { throw 'Get-PimSignedInToken: engine\_shared\PIM-Rest.ps1 is not loaded.' }
    if (-not "$script:PimSignedInSource") { $script:PimSignedInSource = 'browser' }
    return (Get-PimInteractiveToken -Audience $Audience -TenantId $TenantId)
}

function Test-PimSupportSessionCovers {
    <#
      PURE given -State (default: $global:InvardiaSupportState). Is a LIVE Invardia Support session open for -TenantId (and
      -SubscriptionId when given)? The conditions Use-PimSupportAppRestSession requires: a session hashtable with its secret,
      a GUID app id, the same tenant, the subscription among its subscriptions.
    #>
    param([string]$TenantId, [string]$SubscriptionId = '', [object]$State)
    $s = if ($PSBoundParameters.ContainsKey('State')) { $State } else { $global:InvardiaSupportState }
    if (-not ($s -is [hashtable]) -or -not $s.Secret -or "$($s.AppId)" -notmatch $script:PimSignedInGuid) { return $false }
    if (-not "$TenantId".Trim() -or "$($s.TenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return $false }
    $subs = @(@($s.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    if ("$SubscriptionId".Trim() -and -not ($subs -contains "$SubscriptionId".Trim().ToLowerInvariant())) { return $false }
    return $true
}

function Get-PimSignedInIdentityRest {
    <#
      100.41 -- Get-PimSignedInIdentity over REST (no az). The identity is the Invardia Support app's REST session when one
      covers -TenantId + -SubscriptionId (Use-PimSupportAppRestSession), else the person at the keyboard: PIM-Rest's own
      sign-in (the browser, auth code + PKCE). The token's claims are asserted (Test-PimSignedInToken: this tenant, a USER --
      or exactly the support app), then the subscription is read over ARM: it must be visible and belong to -TenantId.
      -Token { param($Resource, $TenantId) <jwt> } and -Arm { param($Path) <object> } are the test seams.
    #>
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$SubscriptionId, [scriptblock]$Token, [scriptblock]$Arm)
    $want = "$TenantId".Trim().ToLowerInvariant(); $sub = "$SubscriptionId".Trim().ToLowerInvariant()
    if ($want -notmatch $script:PimSignedInGuid -or $sub -notmatch $script:PimSignedInGuid) {
        return @{ ok = $false; reason = 'the tenant id and the subscription id must both be given explicitly (GUIDs) -- a signed-in build never relies on a default context' }
    }
    $supportApp = ''
    $script:PimSignedInSubscriptionId = $sub   # the stale-session fallback checks a live session for THIS subscription
    if (-not $Token) {
        if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) {
            $rest = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'engine\_shared\PIM-Rest.ps1'
            if (Test-Path -LiteralPath $rest) { . $rest } else { return @{ ok = $false; reason = 'engine\_shared\PIM-Rest.ps1 is not loaded -- the signed-in identity cannot be read' } }
        }
        $supportApp = Use-PimSupportAppRestSession -TenantId $want -SubscriptionId $sub
        if (-not $supportApp) {
            Set-PimSignedInGlobals -TenantId $want
            # the person signs in in the browser (PIM-Rest: auth code + PKCE) -- only where a person can
            $interactive = $true
            try { if (-not [Environment]::UserInteractive -or [Console]::IsInputRedirected) { $interactive = $false } } catch { }
            $global:PIM_InteractiveFallback = $interactive
        }
        $Token = { param($r, $t) Get-PimRestToken -Resource $r -TenantId $t }
    }
    $tok = ''; $why = ''
    try { $tok = "$(& $Token 'arm' $want)".Trim() } catch { $why = "$($_.Exception.Message)"; $tok = '' }
    if (-not $tok) {
        return @{ ok = $false; reason = ("could not sign in to tenant $want$(if ($why) { " ($why)" }). Run it in a PowerShell window (a browser sign-in opens), " +
                 'or in a shell connected with the Invardia Support app (Connect-InvardiaSupport.ps1 -Environment <handle>).') }
    }
    $allow = $supportApp
    if (-not $allow) {
        # an older connect script's support session, recognised by its environment variables: the token's own app id
        $sess = Get-PimSupportAppSession
        if ($sess -and $sess.tenantId -eq $want -and ($sess.subscriptions -contains $sub)) {
            $c = ConvertFrom-PimJwtClaims -Token $tok
            $allow = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
        }
    }
    $t = Test-PimSignedInToken -Token $tok -TenantId $want -AllowedAppId $allow
    $tok = $null
    if (-not $t.ok) { return $t }
    if (-not $Arm) { $Arm = { param($p) Invoke-PimArm -Method GET -Path $p -ApiVersion '2022-12-01' } }
    $s = $null; $why = ''
    try { $s = & $Arm "/subscriptions/$sub" } catch { $why = "$($_.Exception.Message)"; $s = $null }
    if (-not $s -or "$($s.subscriptionId)".Trim().ToLowerInvariant() -ne $sub) {
        return @{ ok = $false; reason = "subscription $sub is not visible to $($t.userName)$(if ($why) { " ($why)" }) -- REFUSING" }
    }
    if ("$($s.tenantId)".Trim() -and "$($s.tenantId)".Trim().ToLowerInvariant() -ne $want) {
        return @{ ok = $false; reason = "subscription $sub belongs to tenant '$($s.tenantId)', not '$want' -- REFUSING (a wrong default acts in somebody else's directory)" }
    }
    $label = if ($t.supportApp) { "signed in as the Invardia Support app $allow (tenant $want, subscription $sub)" } else { "signed in as $($t.userName) (tenant $want, subscription $sub)" }
    return @{ ok = $true; reason = $label; userName = $t.userName; objectId = $t.objectId; tenantId = $want; subscriptionId = $sub; supportAppId = "$allow" }
}

function Set-PimSignedInGlobals {
    <#
      Make the engine's token helpers (Get-PimRestToken, New-PimSqlConnection) take the signed-in token source in THIS
      process: clear every application-identity global, pin the tenant, and switch the managed-identity probe off (a
      deploy host that is an Azure VM has a managed identity of its own, and it would otherwise win).
    #>
    param([Parameter(Mandatory)][string]$TenantId)
    foreach ($n in 'PIM_ClientId', 'PIM_ClientSecret', 'PIM_CertThumbprint', 'PIM_SqlClientId', 'PIM_SqlClientSecret', 'PIM_SqlCertThumbprint', 'PIM_SqlAccessToken', 'PIM_UseManagedIdentity') {
        Set-Variable -Scope Global -Name $n -Value $null -WhatIf:$false
    }
    $global:PIM_TenantId = "$TenantId".Trim()
    $global:PIM_NoManagedIdentity = $true
    $global:PIM_UseGraphSdk = $false
    $global:PIM_SignedInAccount = $true
    # STALE SUPPORT SESSION: a new run decides its identity afresh (Get-PimSignedInToken) -- never an earlier run's choice
    $script:PimSignedInSource = ''
    # REQ 100.42: register the signed-in token source (Support app / browser) -- PIM-Rest has no other fallback.
    $global:PIM_TokenProvider = ${function:Get-PimSignedInToken}
}

function Connect-PimSignedInSql {
    <#
      Prepare THIS process to reach Azure SQL as the signed-in user, and prove the token is right before any statement
      runs. PIM-Rest.ps1 must be loaded. Returns @{ userName; objectId }. The token itself stays in the engine's
      in-memory cache and is never returned, printed or written.
    #>
    param([Parameter(Mandatory)][string]$TenantId)
    [void](Clear-PimSignedInMachineIdentity); $conf = @(Get-PimSignedInEnvironmentConflicts)
    if ($conf.Count) { throw "REFUSED: $($conf -join ', ') set in this session -- the SQL token would be minted for that identity, not the signed-in user. $(Get-PimSignedInConflictHint -Names $conf)" }
    if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) { throw 'Connect-PimSignedInSql: engine\_shared\PIM-Rest.ps1 is not loaded.' }
    Set-PimSignedInGlobals -TenantId $TenantId
    # 100.41 (no az): the Invardia Support app's REST session for this tenant is the identity when there is one (PIM-Rest
    # client credentials with its secret); else the person's own sign-in.
    $allowApp = Use-PimSupportAppRestSession -TenantId $TenantId
    if (-not $allowApp) {
        $interactive = $true
        try { if (-not [Environment]::UserInteractive -or [Console]::IsInputRedirected) { $interactive = $false } } catch { }
        if (-not $global:PIM_InteractiveFallback) { $global:PIM_InteractiveFallback = $interactive }
    }
    # REQ 100.76: -Force -- a token minted NOW, after this run made the person (or its group) the server's Entra admin; a
    # cached one predates that and SQL refuses it ("Login failed for user '<token-identified principal>'").
    $tok = Get-PimRestToken -Resource 'https://database.windows.net' -TenantId $TenantId -Force
    if (Get-Command Reset-PimSqlTokenCache -ErrorAction SilentlyContinue) { Reset-PimSqlTokenCache }
    if (-not $allowApp) {
        # an older connect script's support session (environment variables): accept exactly the app its token names
        $sess = Get-PimSupportAppSession
        if ($sess -and $sess.tenantId -eq "$TenantId".Trim().ToLowerInvariant()) {
            $c = ConvertFrom-PimJwtClaims -Token "$tok"
            if (-not "$(if ($c.upn) { $c.upn } else { $c.unique_name })".Trim()) { $allowApp = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim() }
        }
    }
    $t = Test-PimSignedInToken -Token "$tok" -TenantId $TenantId -AllowedAppId $allowApp
    $tok = $null
    if (-not $t.ok) { throw "SQL as the signed-in user: $($t.reason)" }
    $global:PIM_SetupActor = $(if ($t.userName) { $t.userName } else { $t.objectId })
    return @{ userName = $t.userName; objectId = $t.objectId }
}

function Get-PimSignedInSqlCreateAdmin {
    <#
      PURE. APP-IDENTITY INSTALL (owner via Invardia 2026-10-21): the SQL server's CREATE-TIME Entra admin for a signed-in
      deploy (-SignedIn = Get-PimSignedInIdentity's answer). The Invardia Support app (supportAppId set) is an APPLICATION,
      never a 'User': principalType Application with its service principal's object id -- the same shape the deploy
      application and the SQL identity already use (New-PimHostingPrerequisites). Either way the admin moves to the SQL
      admin group right after (the prerequisites' group step); this is only who holds it in between.
      @{ principalType; login; sid }.
    #>
    param([Parameter(Mandatory)][object]$SignedIn)
    $app = "$($SignedIn.supportAppId)".Trim()
    if ($app) { return @{ principalType = 'Application'; login = "invardia-support-$($app.ToLowerInvariant())"; sid = "$($SignedIn.objectId)".Trim().ToLowerInvariant() } }
    return @{ principalType = 'User'; login = "$($SignedIn.userName)"; sid = "$($SignedIn.objectId)" }
}

function Invoke-PimSignedInSqlAdminMembership {
    <#
      Make the signed-in user a MEMBER of the SQL admin group of -SqlServerName (members-only: never creates the group,
      never moves the Entra admin). Returns @{ ok; blocked; added; reason }. Blocked = the server's admin is not the
      group, so membership would grant nothing -- the caller must refuse with that reason.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$ResourceGroup,
          [Parameter(Mandatory)][string]$SqlServerName, [Parameter(Mandatory)][string]$UserObjectId, [string]$GroupName = 'grp-pim-sql-admins',
          # APP-IDENTITY INSTALL (2026-10-21): the signed-in principal is an application -- a server whose admin was set by
          # its client id elsewhere is recognised too (a direct admin by either id)
          [string]$AppId = '',
          # test seam: @{ Graph; Arm; TenantId } instead of the signed-in session's REST invokers
          [object]$Invokers)
    # Loaded on demand through a variable path: Build-PimSupportScripts.ps1 inlines the literal dot-source-of-a-Join-Path
    # lines, and a standalone script that inlines THIS file (Initialize-PimMailSender.ps1) never calls this function.
    if (-not (Get-Command Invoke-PimSqlAdminGroupStep -ErrorAction SilentlyContinue)) { $__sag = Join-Path $PSScriptRoot '_PimSqlAdminGroup.ps1'; . $__sag }
    $inv = if ($Invokers) { $Invokers } else { New-PimSqlAdminGroupInvokers -SubscriptionId $SubscriptionId -TenantId $TenantId }
    $srv = ("$SqlServerName".Trim() -split '\.')[0]
    $sqlRg = $ResourceGroup
    if (Get-Command Resolve-PimSqlServerFromFqdn -ErrorAction SilentlyContinue) {
        try { $res = Resolve-PimSqlServerFromFqdn -Arm $inv.Arm -SubscriptionId $SubscriptionId -Server $srv; if ($res) { $sqlRg = $res.resourceGroup; $srv = $res.name } } catch { }
    }
    # §95.2 Cloud Shell blocker 5 (guided install): an installer WITHOUT Privileged Role Administrator cannot create the
    # role-assignable SQL admin group, so the prerequisites leave the server's Entra admin = the signed-in user. That user
    # already holds every SQL right; the members-only step would only fail on "group does not exist". Say so, hand the
    # group to a Privileged Role Administrator, and let the deploy continue.
    try {
        $list = & $inv.Arm -Method GET -Path "/subscriptions/$SubscriptionId/resourceGroups/$sqlRg/providers/Microsoft.Sql/servers/$srv/administrators?api-version=$($script:PimSqlApi)"
        $cur = @(@($list.value) | Where-Object { $_ }) | Select-Object -First 1
        if ($cur -and ("$($cur.properties.sid)".Trim() -ieq "$UserObjectId".Trim() -or ("$AppId".Trim() -and "$($cur.properties.sid)".Trim() -ieq "$AppId".Trim()))) {
            $action = ".\Initialize-PimSqlAdminGroup.ps1 -SubscriptionId $SubscriptionId -TenantId $TenantId -ResourceGroup $sqlRg -SqlServerName $srv -GroupName $GroupName"
            Write-Host "    the signed-in user IS the Entra admin of $srv -- SQL is reachable. The SQL admin group '$GroupName' is not the admin yet; a Privileged Role Administrator converges it with: $action" -ForegroundColor Yellow
            return @{ ok = $true; blocked = $false; added = $false; direct = $true; reason = ''; action = $action }
        }
    } catch { Write-Verbose "reading the Entra admin of $srv failed: $($_.Exception.Message) -- falling back to the group membership" }
    $r = Invoke-PimSqlAdminGroupStep -Graph $inv.Graph -Arm $inv.Arm -TenantId $inv.TenantId -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup `
            -SqlResourceGroup $sqlRg -SqlServerName $srv -GroupName $GroupName -UpdateJobName '' -NoDiscovery -Mode membersOnly `
            -ExtraMembers @([pscustomobject]@{ objectId = "$UserObjectId".Trim(); label = 'the signed-in administrator' })
    Write-PimSqlAdminGroupReport -Result $r
    $added = @(@($r.added) | Where-Object { "$($_.objectId)" -ieq "$UserObjectId".Trim() }).Count -gt 0
    if (-not $r.ok) { return @{ ok = $false; blocked = $false; added = $added; reason = "could not make the signed-in user a member of '$GroupName': $(@($r.problems) -join '; ')" } }
    if ($r.blocked) { return @{ ok = $true; blocked = $true; added = $false; reason = "the Entra admin of $srv is not '$GroupName' ($($r.blocked)) -- membership grants nothing there. Converge the server onto the group first (Initialize-PimSqlAdminGroup.ps1), or make the signed-in user the Entra admin." } }
    if ($added) {
        Write-Host ("    NOTE: you were ADDED to '$GroupName' just now. An Entra token carries group membership as of when it was issued, " +
                    'and a sign-in token is reused for up to about an hour -- if SQL refuses the next step, open a NEW PowerShell window, sign in again (browser, or Connect-InvardiaSupport.ps1) and resume.') -ForegroundColor Yellow
    }
    return @{ ok = $true; blocked = $false; added = $added; reason = '' }
}

# ===== END inlined helper: _PimSignedIn.ps1 =====
# ===== BEGIN inlined helper: _PimSupportSqlAccess.ps1 =====
<#
.SYNOPSIS
  PIM REQUIREMENTS 100.116 (framework 4.1b) -- the Invardia Support app's STANDING access to the PIM database: its own
  database user, created from the application's CLIENT id in SID form, in the READ role pim_support_read (OPEN-01; before
  OPEN-01 this was the database owner role plus the SQL admin group membership -- both are now only read). Shared by the install (Grant-PimSupportAccess.ps1), the one-time script for existing installs
  (Grant-PimSupportSqlAccess.ps1) and the end-of-install check (Confirm-PimInstall.ps1).

  OPEN-01 (framework SECAUDIT-1a, 2026-11-05): the Support app's ONLY standing database right is its own user in the
  read role pim_support_read (PIM-SupportJit.ps1 Get-PimSupportJitReadOnlyRole); admin rights exist only inside an open
  support session. A NEW install (Grant-PimSupportAccess.ps1) and its check (Confirm-PimInstall.ps1) use that role, and
  so do the one-time script for an existing install (Grant-PimSupportSqlAccess.ps1, Invoke-PimSupportSqlReadOnlyUser
  below) and the job's 'standing' mode. Nothing here adds the Support app to db_owner or to the SQL admin group: the
  write statement takes the read role only (Get-PimSupportSqlUserSql refuses any other), and the group is only READ
  (Get-PimSupportSqlAdminGroupMember). A db_owner or a membership an earlier version gave is REPORTED, never kept as
  "in place" and never removed here (its removal is a separate, owner-approved step).

.DESCRIPTION
  Why a database user and not only the group: membership of the SQL admin group has not given an APPLICATION a database
  sign-in on the servers this was measured on ("Login failed for user '<token-identified principal>'" with the group in
  the token). A contained user made from the client id needs no directory lookup and works at once.

  The user is looked up BY SID, never by name: one SID can exist once in a database, so an earlier grant under another
  name (Grant-PimSupportAccess -Level troubleshoot makes [invardia-support]) is found and reused, never duplicated.

  Two SQL facts this file is written around (measured, PIM REQUIREMENTS 100.116):
    * EXEC('...' + QUOTENAME(@n)) is a syntax error -- the statement is built in a variable first, then run;
    * joining text to a name column of sys.database_principals needs COLLATE DATABASE_DEFAULT.

  Nothing here signs in. Every caller hands in:
    -Arm   { param([string]$Method, [string]$Path, $Body) }  ARM, the path carries its api-version; throws "... HTTP <code> ..."
    -Graph { param([string]$Method, [string]$Path, $Body) }  Microsoft Graph v1.0
    -Sql   { param([string]$Query) }                         ONE scalar from the PIM database, a new sign-in each call
  Defaults are functions that return a literal (a $script: variable is $null in a child script scope).
#>

function Get-PimSupportSqlUserDefaultName { return 'invardia-support' }
# OPEN-01: the ONE role this file ever adds the Support app's user to -- the read role (the literal of
# PIM-SupportJit.ps1 Get-PimSupportJitReadOnlyRole; a literal here, so the job carries it without that file's order)
function Get-PimSupportSqlRoleName { return 'pim_support_read' }
# OPEN-01: the roles an EARLIER version gave the Support app's user -- read and reported, never added, never removed here
function Get-PimSupportSqlLegacyRoleNames { return @('db_owner', 'db_datareader') }
function Get-PimSupportSqlArmApi { return '2021-11-01' }
function Get-PimSupportSqlHostRuleName { return 'AllowSetupHost' }
function Get-PimSupportSqlScriptName { return 'Grant-PimSupportSqlAccess' }

function ConvertTo-PimSupportSqlSid {
    # PURE. The application's CLIENT id as a SQL SID literal: the GUID's bytes in ToByteArray order, as hex.
    param([Parameter(Mandatory)][string]$AppId)
    $t = "$AppId".Trim()
    if ($t -notmatch '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') { throw "ConvertTo-PimSupportSqlSid: '$AppId' is not an application (client) id." }
    $g = [guid]$t
    if ($g -eq [guid]::Empty) { throw 'ConvertTo-PimSupportSqlSid: the empty id is not an application (client) id.' }
    return ('0x' + ((@($g.ToByteArray()) | ForEach-Object { $_.ToString('X2') }) -join ''))
}

function Test-PimSupportSqlNames {
    # PURE. Throws on a user or role name that is not safe to put into a statement: a fixed database role, or the support
    # read role pim_support_read (OPEN-01) -- nothing else.
    param([string]$DbUserName, [string]$Role)
    if ("$DbUserName" -notmatch '^[A-Za-z0-9][A-Za-z0-9 ._@-]{0,127}$') { throw "'$DbUserName' is not a safe database user name." }
    if ("$Role" -cnotmatch '^(db_[a-z]{3,30}|pim_support_read)$') { throw "'$Role' is not a fixed database role or the support read role." }
}

function Get-PimSupportSqlUserSql {
    <#
      PURE. The statement that puts the Support app's database user in place. Idempotent:
        no principal has the SID -> CREATE USER [<name>] WITH SID = <sid>, TYPE = E
        the principal with that SID (whatever its name) is not in the role -> ALTER ROLE ... ADD MEMBER
      OPEN-01: the role is the read role and nothing else -- a write statement for db_owner (or any other role) is REFUSED.
    #>
    param([Parameter(Mandatory)][string]$AppId, [string]$DbUserName = (Get-PimSupportSqlUserDefaultName), [string]$Role = (Get-PimSupportSqlRoleName))
    Test-PimSupportSqlNames -DbUserName $DbUserName -Role $Role
    if ("$Role" -cne (Get-PimSupportSqlRoleName)) { throw "the Support app's database user is only ever added to $(Get-PimSupportSqlRoleName) -- not to '$Role'." }
    $sid = ConvertTo-PimSupportSqlSid -AppId $AppId
    $q = '[' + "$DbUserName".Replace(']', ']]') + ']'
    $l = New-Object System.Collections.Generic.List[string]
    $l.Add("IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE sid = $sid)")
    $l.Add("    CREATE USER $q WITH SID = $sid, TYPE = E;")
    $l.Add("DECLARE @n SYSNAME = (SELECT TOP 1 name FROM sys.database_principals WHERE sid = $sid);")
    $l.Add("IF @n IS NOT NULL AND NOT EXISTS (SELECT 1 FROM sys.database_role_members m JOIN sys.database_principals r ON r.principal_id = m.role_principal_id JOIN sys.database_principals p ON p.principal_id = m.member_principal_id WHERE r.name = N'$Role' AND p.sid = $sid)")
    $l.Add('BEGIN')
    # the statement is built in a variable FIRST: EXEC('...' + QUOTENAME(@n)) is a syntax error
    $l.Add("    DECLARE @q NVARCHAR(600) = N'ALTER ROLE [$Role] ADD MEMBER ' + QUOTENAME(@n) + N';';")
    $l.Add('    EXEC sp_executesql @q;')
    $l.Add('END')
    return ($l -join "`r`n")
}

function Get-PimSupportSqlUserReadSql {
    <#
      PURE. ONE scalar that says what is there: '<in role 0|1>|<name taken by another id 0|1>|<name of the user with the SID>'.
      The name is last (it is the only free text) and carries COLLATE DATABASE_DEFAULT: a catalog name column cannot be
      joined to text without it.
    #>
    param([Parameter(Mandatory)][string]$AppId, [string]$DbUserName = (Get-PimSupportSqlUserDefaultName), [string]$Role = (Get-PimSupportSqlRoleName))
    Test-PimSupportSqlNames -DbUserName $DbUserName -Role $Role
    $sid = ConvertTo-PimSupportSqlSid -AppId $AppId
    $n = "$DbUserName".Replace("'", "''")
    return ("SELECT CAST((SELECT COUNT(*) FROM sys.database_role_members m JOIN sys.database_principals r ON r.principal_id = m.role_principal_id JOIN sys.database_principals p ON p.principal_id = m.member_principal_id WHERE r.name = N'$Role' AND p.sid = $sid) AS NVARCHAR(10))" +
            " + N'|' + CAST((SELECT COUNT(*) FROM sys.database_principals WHERE name = N'$n' AND (sid IS NULL OR sid <> $sid)) AS NVARCHAR(10))" +
            " + N'|' + ISNULL((SELECT TOP 1 name COLLATE DATABASE_DEFAULT FROM sys.database_principals WHERE sid = $sid), N'')")
}

function Get-PimSupportSqlUserDropSql {
    # PURE. Take the access back: drop the user that has the Support app's id, whatever its name. Nothing when there is none.
    param([Parameter(Mandatory)][string]$AppId)
    $sid = ConvertTo-PimSupportSqlSid -AppId $AppId
    return (@("DECLARE @n SYSNAME = (SELECT TOP 1 name FROM sys.database_principals WHERE sid = $sid);",
              'IF @n IS NOT NULL',
              'BEGIN',
              "    DECLARE @q NVARCHAR(600) = N'DROP USER ' + QUOTENAME(@n) + N';';",
              '    EXEC sp_executesql @q;',
              'END') -join "`r`n")
}

function ConvertFrom-PimSupportSqlUserRead {
    # PURE. The scalar of Get-PimSupportSqlUserReadSql -> @{ inRole; nameTaken; userName }. Anything else THROWS (no answer is never "absent").
    param([AllowNull()]$Raw)
    $t = "$Raw"
    if ($t -notmatch '^(\d+)\|(\d+)\|(.*)$') { throw 'the database did not answer the read of the Support app''s database user' }
    return @{ inRole = ([int]$Matches[1] -ge 1); nameTaken = ([int]$Matches[2] -ge 1); userName = "$($Matches[3])" }
}

function Invoke-PimSupportSqlUser {
    <#
      Put the Support app's database user in place through -Sql and READ IT BACK. Never throws.
      Returns { ok; existed; created; userName; inRole; role; problem }.
        -ReadOnly : read only (the check, a preview)
      A user of the wanted NAME that belongs to ANOTHER id is never dropped or reused: reported, nothing changed.
    #>
    param([Parameter(Mandatory)][scriptblock]$Sql, [Parameter(Mandatory)][string]$AppId,
          [string]$DbUserName = (Get-PimSupportSqlUserDefaultName), [string]$Role = (Get-PimSupportSqlRoleName), [switch]$ReadOnly)
    $o = [ordered]@{ ok = $false; existed = $false; created = $false; userName = ''; inRole = $false; role = $Role; problem = '' }
    try {
        $readSql = Get-PimSupportSqlUserReadSql -AppId $AppId -DbUserName $DbUserName -Role $Role
        $b = ConvertFrom-PimSupportSqlUserRead (& $Sql $readSql)
        $o.existed = [bool]$b.userName; $o.userName = $b.userName; $o.inRole = [bool]$b.inRole
        if ($o.existed -and $o.inRole) { $o.ok = $true; return [pscustomobject]$o }
        if ($ReadOnly) {
            $o.problem = if ($o.existed) { "the database user [$($o.userName)] of the Support app is not in $Role" } else { 'the Support app has no database user' }
            return [pscustomobject]$o
        }
        if (-not $o.existed -and $b.nameTaken) {
            $o.problem = "a database user named [$DbUserName] exists but belongs to ANOTHER id (an earlier Support app) -- nothing was changed. Run again with -DbUserName <another name>, or drop the old user first."
            return [pscustomobject]$o
        }
        [void](& $Sql (Get-PimSupportSqlUserSql -AppId $AppId -DbUserName $DbUserName -Role $Role))
        $a = ConvertFrom-PimSupportSqlUserRead (& $Sql $readSql)
        $o.userName = $a.userName; $o.inRole = [bool]$a.inRole
        $o.created = ([bool]$a.userName -and -not $o.existed)
        if ($a.userName -and $a.inRole) { $o.ok = $true }
        else { $o.problem = "read-back: $(if ($a.userName) { "the database user [$($a.userName)] is not in $Role" } else { 'no database user has the Support app''s id' }) after the statement ran" }
    } catch { $o.problem = (("$($_.Exception.Message)" -split "`n")[0]).Trim() }
    return [pscustomobject]$o
}

function Invoke-PimSupportSqlReadOnlyUser {
    <#
      OPEN-01 (framework SECAUDIT-1a): the Support app's ONE standing database right on an EXISTING install -- the same step
      a new install takes (Grant-PimSupportAccess.ps1): the support access module (PIM-SupportJit.ps1
      Invoke-PimSupportJitInstall) with a consent level, which makes the user from the client id (by SID; an existing user
      of the Support app is reused whatever its name) in the read role only; then READ BACK by SID. Never db_owner, never
      db_datareader, never the SQL admin group. What an EARLIER version gave (db_owner, db_datareader) is read and REPORTED
      (legacy; legacyOwner = db_owner held while no support session is open) -- never "in place", never removed here.
      -ConsentLevel troubleshoot | setup; '' = the level already recorded on this install (troubleshoot or setup), else
      troubleshoot -- a re-run keeps the level the customer recorded. Needs an owner-level -Sql sign-in.
      -ReadOnly: reads only (a preview, a check).
      Needs PIM-SupportJit.ps1 loaded. Never throws.
      Returns { ok; existed; created; userName; inRole; role; consented; legacy; legacyOwner; sessionOpen; problem }.
    #>
    param([Parameter(Mandatory)][scriptblock]$Sql, [Parameter(Mandatory)][string]$AppId, [string]$DbUserName = (Get-PimSupportSqlUserDefaultName),
          [ValidateSet('', 'troubleshoot', 'setup')][string]$ConsentLevel = '', [string]$SetBy = '', [switch]$ReadOnly)
    $role = Get-PimSupportSqlRoleName
    $o = [ordered]@{ ok = $false; existed = $false; created = $false; userName = ''; inRole = $false; role = $role; consented = ''; legacy = @(); legacyOwner = $false; sessionOpen = $false; problem = '' }
    try {
        # the user of the Support app's id, whatever its name: the one every statement below uses. A user of the wanted NAME
        # that belongs to ANOTHER id is never dropped or reused: reported, nothing changed.
        $pre = ConvertFrom-PimSupportSqlUserRead (& $Sql (Get-PimSupportSqlUserReadSql -AppId $AppId -DbUserName $DbUserName -Role $role))
        if ("$($pre.userName)".Trim()) { $o.existed = $true; $DbUserName = "$($pre.userName)" }
        elseif ($pre.nameTaken) {
            $o.problem = "a database user named [$DbUserName] exists but belongs to ANOTHER id (an earlier Support app) -- nothing was changed. Run again with -DbUserName <another name>, or drop the old user first."
            return [pscustomobject]$o
        }
        $st = Get-PimSupportJitState -Sql $Sql
        if (-not $st.read -and $st.installed -ne $false) { throw "the support access state could not be read ($($st.problem))" }
        $consent = "$ConsentLevel".Trim().ToLowerInvariant()
        if (-not $consent) {
            $cur = ConvertTo-PimSupportJitLevel "$($st.consented)"
            $consent = if ($st.read -and $cur -in @('troubleshoot', 'setup')) { $cur } else { 'troubleshoot' }
        }
        $o.consented = $consent
        if (-not $ReadOnly) {
            $ji = Invoke-PimSupportJitInstall -Sql $Sql -SupportAppId $AppId -ConsentLevel $consent -UserName $DbUserName -SetBy $SetBy
            if (-not $ji.ok) { $o.problem = "the support access step: $(@($ji.problems) -join '; ')" }
            $st = Get-PimSupportJitState -Sql $Sql
        }
        $o.sessionOpen = [bool]($st.read -and $st.jitOpen)
        $a = Invoke-PimSupportSqlUser -Sql $Sql -AppId $AppId -DbUserName $DbUserName -Role $role -ReadOnly
        $o.userName = "$($a.userName)"; $o.inRole = [bool]$a.inRole
        $o.created = ([bool]$o.userName -and -not $o.existed)
        foreach ($lr in @(Get-PimSupportSqlLegacyRoleNames)) {
            $l = Invoke-PimSupportSqlUser -Sql $Sql -AppId $AppId -DbUserName $DbUserName -Role $lr -ReadOnly
            if ($l.inRole) { $o.legacy = @($o.legacy) + @($lr) }
        }
        $o.legacyOwner = [bool]((@($o.legacy) -contains 'db_owner') -and -not $o.sessionOpen)
        if (-not $o.problem -and -not $o.inRole) {
            $o.problem = if ($ReadOnly) { "$(if ($o.userName) { "the database user [$($o.userName)] of the Support app is not in $role" } else { 'the Support app has no database user' })" }
                         else { "read-back: $(if ($o.userName) { "the database user [$($o.userName)] is not in $role" } else { 'no database user has the Support app''s id' }) after the support access step ran" }
        }
        $o.ok = [bool](-not $o.problem -and $o.inRole)
    } catch { $o.problem = (("$($_.Exception.Message)" -split "`n")[0]).Trim() }
    return [pscustomobject]$o
}

function Get-PimSupportSqlLegacyText {
    # PURE. One plain line for what an EARLIER version left the Support app (-Legacy roles, -Member of the SQL admin group);
    # '' when nothing. Said, never added again, never removed by this step.
    param([string[]]$Legacy = @(), [bool]$Member = $false, [string]$GroupName = 'grp-pim-sql-admins', [bool]$SessionOpen = $false)
    $parts = New-Object System.Collections.Generic.List[string]
    foreach ($r in @($Legacy | Where-Object { "$_".Trim() })) {
        if ($r -eq 'db_owner' -and $SessionOpen) { continue }   # inside an open support session db_owner is the session's
        $parts.Add("in $r")
    }
    if ($Member) { $parts.Add("a member of the SQL admin group '$GroupName'") }
    if (-not $parts.Count) { return '' }
    return "from an earlier grant the Invardia Support app is still $($parts -join ', ') -- this run did not add it and left it as found. Removing it is a separate step the owner approves."
}

function Get-PimSupportSqlAdminGroupMember {
    <#
      OPEN-01 (framework SECAUDIT-1a): READ whether the Support app's service principal is a member of the SQL admin group.
      Never writes, never throws. (Before OPEN-01 this added the membership; no code path adds it any more.)
      Returns { state; detail; spObjectId; spName; groupId }:
        member      a member (from an earlier version: reported by the caller, left as found)
        not-member  not a member (no standing administrator right)
        no-group    the group does not exist in this tenant
        no-sp       the application has no service principal here
        refused     the membership could not be read
      -GroupId (33.0 item 5, 2026-10-20): the group's object id when the caller knows it (the SQL server's Entra
      administrator, principalType Group: its sid IS the group's object id). The group is then read BY ID and its name
      may be anything (a renamed group is still found); the display-name filter is only the fallback when no id is
      given or the id does not read.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$SupportAppId, [string]$GroupName = 'grp-pim-sql-admins', [string]$GroupId = '')
    $o = [ordered]@{ state = ''; detail = ''; spObjectId = ''; spName = ''; groupId = '' }
    try {
        $f = [uri]::EscapeDataString("appId eq '$("$SupportAppId".Trim())'")
        $sp = @((& $Graph 'GET' "/servicePrincipals?`$select=id,appId,displayName&`$filter=$f" $null).value | Where-Object { $_ }) | Select-Object -First 1
        if (-not $sp -or -not "$($sp.id)".Trim()) { $o.state = 'no-sp'; $o.detail = "the application $SupportAppId has no service principal in this tenant"; return [pscustomobject]$o }
        $o.spObjectId = "$($sp.id)".Trim(); $o.spName = "$($sp.displayName)".Trim()
        $gid = ''
        # 33.0 item 5 (2026-10-20): by id first -- the name is configurable and may be renamed; the id never changes
        if ("$GroupId".Trim()) {
            try {
                $gById = & $Graph 'GET' "/groups/$([uri]::EscapeDataString("$GroupId".Trim()))?`$select=id,displayName" $null
                if ($gById -and "$($gById.id)".Trim()) { $gid = "$($gById.id)".Trim(); if ("$($gById.displayName)".Trim()) { $GroupName = "$($gById.displayName)".Trim() } }
            } catch { $gid = '' }
        }
        if (-not $gid) {
            $gf = [uri]::EscapeDataString("displayName eq '$($GroupName.Replace("'", "''"))'")
            $grps = @((& $Graph 'GET' "/groups?`$select=id,displayName&`$filter=$gf" $null).value | Where-Object { $_ })
            if (-not $grps.Count) { $o.state = 'no-group'; $o.detail = "the group '$GroupName' does not exist in this tenant"; return [pscustomobject]$o }
            if ($grps.Count -gt 1) { $o.state = 'refused'; $o.detail = "$($grps.Count) groups are named '$GroupName' -- not changed"; return [pscustomobject]$o }
            $gid = "$($grps[0].id)".Trim()
        }
        $o.groupId = $gid
        # 2.4.649 (live 2026-10-18): GET /groups/{id}/members LEAVES OUT service principals the caller cannot read -- at 16
        # installs the Support app was a member while the list showed 0-1 members. Asked from the MEMBER's side first
        # (checkMemberObjects is a POST that reads, it changes nothing); the list below stays as the fallback.
        try {
            $cmo = & $Graph 'POST' "/servicePrincipals/$($o.spObjectId)/checkMemberObjects" @{ ids = @($gid) }
            if (@($cmo.value) -contains $gid) { $o.state = 'member'; $o.detail = "already a member of '$GroupName'"; return [pscustomobject]$o }
        } catch { }
        $ids = New-Object System.Collections.Generic.List[string]
        $next = "/groups/$gid/members?`$select=id&`$top=999"
        while ($next) {
            $page = & $Graph 'GET' $next $null
            foreach ($m in @($page.value)) { if ($m -and "$($m.id)".Trim()) { $ids.Add("$($m.id)".Trim().ToLowerInvariant()) } }
            $next = "$($page.'@odata.nextLink')".Trim()
        }
        if ($ids.Contains($o.spObjectId.ToLowerInvariant())) { $o.state = 'member'; $o.detail = "already a member of '$GroupName'"; return [pscustomobject]$o }
        $o.state = 'not-member'; $o.detail = "not a member of '$GroupName'"
    } catch { $o.state = 'refused'; $o.detail = "the group membership could not be read: $((("$($_.Exception.Message)" -split "`n")[0]).Trim())" }
    return [pscustomobject]$o
}

function Get-PimSupportSqlAdminSnapshot {
    # PURE. The server's Entra administrator EXACTLY as the server object carries it (only the properties that are there).
    param([AllowNull()]$Server)
    $a = $null
    if ($Server -and $Server.properties) { $a = $Server.properties.administrators }
    if (-not $a -or -not "$($a.sid)".Trim()) { return $null }
    $o = [ordered]@{}
    foreach ($k in 'administratorType', 'principalType', 'login', 'sid', 'tenantId') { if ($null -ne $a.$k -and "$($a.$k)" -ne '') { $o[$k] = "$($a.$k)" } }
    if ($null -ne $a.azureADOnlyAuthentication) { $o['azureADOnlyAuthentication'] = [bool]$a.azureADOnlyAuthentication }
    return $o
}

function Compare-PimSupportSqlAdmin {
    # PURE. The differences between the administrator that was read (-Want) and what is there now (-Have); none = the same.
    param([AllowNull()]$Want, [AllowNull()]$Have)
    $d = New-Object System.Collections.Generic.List[string]
    if (-not $Want) { return @() }
    if (-not $Have) { return @('the server has no Entra administrator now') }
    foreach ($k in @($Want.Keys)) {
        $w = "$($Want[$k])"; $h = "$($Have[$k])"
        $same = if ($k -eq 'login') { $w -ceq $h } else { $w -ieq $h }
        if (-not $same) { $d.Add("$k is '$h', was '$w'") }
    }
    return @($d.ToArray())
}

function Get-PimSupportSqlFixCommand {
    # PURE. The two lines a person runs for an existing install: the download, then the run (framework 12.10 item 11).
    param([string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup, [string]$SqlServerName, [string]$SupportAppId)
    $name = Get-PimSupportSqlScriptName
    $srv = ("$SqlServerName".Trim() -split '\.')[0]
    $run = ".\$name.ps1 -TenantId '$TenantId' -SubscriptionId '$SubscriptionId' -ResourceGroup '$ResourceGroup' -SqlServerName '$srv' -SupportAppId '$SupportAppId'"
    return @(Get-PimSupportScriptCommand -Script $name -Run @($run))
}

function Invoke-PimSupportSqlAccessGrant {
    <#
      The one-time step for an EXISTING install (PIM REQUIREMENTS 100.116, the method measured at a customer; OPEN-01
      read-only model, framework SECAUDIT-1a):
        1. read and keep the server's Entra administrator and the Entra-only setting; read the setup-host firewall rule
        2. READ whether the Support app is a member of the SQL admin group -- never added; a membership an earlier version
           gave is a WARNING (reported, left as found)
        3. open the install's own setup-host firewall rule (only when it is not there; a rule of another address stops the run)
        4. try a database sign-in as this session. Refused, and this session IS the Support app: make the Support app the
           server's administrator FOR THE STEP (PATCH of the server, the Entra-only setting sent back as read) and wait
           until a database sign-in answers
        5. the support access step (Invoke-PimSupportSqlReadOnlyUser): the user from the client id in pim_support_read
           only; read back. An earlier db_owner / db_datareader is a WARNING (reported, never kept as "in place")
        6. finally: put the administrator back EXACTLY as read and read it back; remove the firewall rule this run opened
           and read that back -- also after a failed step
        7. proof: a new database sign-in as the Support app (a Support session only; otherwise "not checked")
      -WhatIfOnly: steps 1 and 2 are READ, the rest is printed. Nothing is written.
      Never throws. Returns { ok; exit (0 done, 1 not done, 2 the administrator was NOT put back); whatIf; before; after; swapped;
      restored; ruleOpened; ruleClosed; group; user; proof; warnings; problems }.
    #>
    param(
        [Parameter(Mandatory)][scriptblock]$Arm,
        [scriptblock]$Graph,
        [scriptblock]$Sql,
        [Parameter(Mandatory)][string]$TenantId,
        [Parameter(Mandatory)][string]$SubscriptionId,
        [Parameter(Mandatory)][string]$ResourceGroup,
        [Parameter(Mandatory)][string]$SqlServerName,
        [string]$SqlDatabase = 'PimPlatform',
        [Parameter(Mandatory)][string]$SupportAppId,
        [bool]$SessionIsSupportApp = $false,
        [string]$DbUserName = (Get-PimSupportSqlUserDefaultName),
        [string]$SqlAdminGroupName = 'grp-pim-sql-admins',
        [string]$HostIp = '',
        [int]$SignInWaitSeconds = 300,
        [int]$PollSeconds = 20,
        [int]$ReadBackTries = 36,
        [int]$FirewallWaitSeconds = 30,
        [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds },
        # can this machine open a TCP connection to <host>:<port>? (a private server's endpoint, from inside the network)
        [scriptblock]$Reach = { param([string]$HostName, [int]$Port)
            $c = New-Object System.Net.Sockets.TcpClient
            try { $t = $c.ConnectAsync($HostName, $Port); return ($t.Wait(8000) -and $c.Connected) } catch { return $false } finally { $c.Close() } },
        [string[]]$FixCommand = @(),
        # OPEN-01: the consent level recorded with the read-only user ('' = the level already recorded, else troubleshoot)
        [ValidateSet('', 'troubleshoot', 'setup')][string]$ConsentLevel = '',
        [switch]$WhatIfOnly
    )
    $role = Get-PimSupportSqlRoleName
    $rule = Get-PimSupportSqlHostRuleName
    $api = Get-PimSupportSqlArmApi
    $srv = ("$SqlServerName".Trim() -replace '^tcp:', '' -replace ',\d+$', '').Split('.')[0].ToLowerInvariant()
    $srvPath = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Sql/servers/$srv"
    $warnings = New-Object System.Collections.Generic.List[string]
    $problems = New-Object System.Collections.Generic.List[string]
    $res = [ordered]@{ ok = $false; exit = 1; whatIf = [bool]$WhatIfOnly; before = $null; after = $null; swapped = $false; restored = $false
                       ruleOpened = $false; ruleClosed = $false; group = $null; user = $null; proof = @{ state = 'not-checked'; detail = '' }
                       warnings = @(); problems = @() }
    $say = { param([string]$m, [string]$c = 'Gray') Write-Host "  $m" -ForegroundColor $c }
    $first = { param($e) (("$($e.Exception.Message)" -split "`n")[0]).Trim() }
    $get = {
        param([string]$P)
        try { return (& $Arm 'GET' "$P`?api-version=$api" $null) }
        catch { if ("$($_.Exception.Message)" -match '(?i)HTTP 404\b|ResourceNotFound|was not found|NotFound') { return $null }; throw }
    }
    $adOnly = {
        $x = & $get "$srvPath/azureADOnlyAuthentications/Default"
        if ($x -and $x.properties -and $null -ne $x.properties.azureADOnlyAuthentication) { return [bool]$x.properties.azureADOnlyAuthentication }
        return $null
    }
    $ruleIp = { $x = & $get "$srvPath/firewallRules/$rule"; if ($x -and $x.properties) { return "$($x.properties.startIpAddress)".Trim() }; return '' }
    $show = {
        param([string]$Label, $Admin, $EntraOnly, [string]$RuleNow)
        & $say ("{0} administrator: {1}; Entra-only sign-in: {2}; firewall rule '{3}': {4}" -f $Label,
            $(if ($Admin) { "'$($Admin['login'])' ($(if ($Admin.Contains('principalType')) { $Admin['principalType'] } else { 'type not given' }), id $($Admin['sid']))" } else { 'none read' }),
            $(if ($null -eq $EntraOnly) { 'not read' } elseif ($EntraOnly) { 'on' } else { 'off' }), $rule, $(if ($RuleNow) { $RuleNow } else { 'not there' }))
    }
    $finish = {
        $res.warnings = @($warnings.ToArray()); $res.problems = @($problems.ToArray())
        $res.exit = if ($res.swapped -and -not $res.restored) { 2 } elseif ($problems.Count) { 1 } else { 0 }
        $res.ok = ($res.exit -eq 0)
        return [pscustomobject]$res
    }

    # ---- 1. read and keep -----------------------------------------------------------------------------------------
    $server = $null; $before = $null; $adOnlyBefore = $null; $ruleBefore = ''
    try {
        $server = & $get $srvPath
        if (-not $server) { $problems.Add("the SQL server '$srv' was not found in resource group '$ResourceGroup' (subscription $SubscriptionId)"); return (& $finish) }
        $before = Get-PimSupportSqlAdminSnapshot -Server $server
        $adOnlyBefore = & $adOnly
        $ruleBefore = & $ruleIp
    } catch { $problems.Add("the SQL server could not be read: $(& $first $_) -- nothing was changed"); return (& $finish) }
    $res.before = @{ admin = $before; entraOnly = $adOnlyBefore; rule = $ruleBefore }
    & $show 'before:' $before $adOnlyBefore $ruleBefore

    # ---- what stops the run BEFORE anything is changed (the group membership below is the first change) --------------
    # A PRIVATE server (public access off) is reached through its private endpoint from inside the network -- a firewall rule
    # does nothing there, so none is opened. Decided by REACHING it, not by the setting alone (a customer 2026-10-21: the run stopped
    # on a machine inside the network that reached the server on 1433 through the private endpoint).
    $private = ("$($server.properties.publicNetworkAccess)" -ieq 'Disabled')
    if ($private) {
        $fqdn = "$srv.database.windows.net"
        $reachable = $false; try { $reachable = [bool](& $Reach $fqdn 1433) } catch { $reachable = $false }
        if (-not $reachable) {
            $problems.Add("the SQL server $srv is private (public network access off) and $fqdn is not reachable on port 1433 from this machine. Run this script from a machine inside the PIM network (check: Test-NetConnection $fqdn -Port 1433). Nothing was changed.")
            return (& $finish)
        }
        & $say "the SQL server $srv is private and reachable from this machine on port 1433 (private endpoint) -- no firewall rule is needed" 'Green'
    }
    $ip = "$HostIp".Trim()
    if (-not $private -and $ruleBefore -and $ip -and $ruleBefore -ne $ip) {
        $problems.Add("the firewall rule '$rule' is already on $srv for another address ($ruleBefore) -- another setup run may be using it, so it is not changed. When no install is running: Azure portal > SQL server $srv > Networking > Firewall rules: delete '$rule', then run this script again. Nothing was changed.")
        return (& $finish)
    }
    if (-not $WhatIfOnly) {
        if (-not $Sql) { $problems.Add('no database session in this run -- nothing was changed'); return (& $finish) }
        if (-not $private -and -not $ruleBefore -and $ip -notmatch '^\d{1,3}(\.\d{1,3}){3}$') { $problems.Add("this machine's public address is not known ('$ip') -- pass -SetupHostIp <address>. Nothing was changed."); return (& $finish) }
    }

    # ---- 2. the SQL admin group: READ only (OPEN-01 -- the Support app is never made a standing administrator) ------
    if ($Graph) {
        # 33.0 item 5 (2026-10-20): the administrator read in step 1 IS the group when it is one -- found by its id, not its name
        $admGid = if ($before -and "$($before['principalType'])" -ieq 'Group' -and "$($before['sid'])".Trim()) { "$($before['sid'])".Trim() } else { '' }
        $g = Get-PimSupportSqlAdminGroupMember -Graph $Graph -SupportAppId $SupportAppId -GroupName $SqlAdminGroupName -GroupId $admGid
        $res.group = $g
        switch ("$($g.state)") {
            'member'     { $warnings.Add((Get-PimSupportSqlLegacyText -Member $true -GroupName $SqlAdminGroupName)) }
            'not-member' { & $say "SQL admin group: the Invardia Support app is $($g.detail) (no standing administrator right; this run does not add it)" 'Green' }
            'no-group'   { & $say "SQL admin group: $($g.detail) -- nothing to read (this run never adds the Support app to it)" 'DarkGray' }
            'no-sp'      { $problems.Add("$($g.detail) -- create the Invardia Support app in this tenant first (Invardia's New-InvardiaSupportApp.ps1); nothing was changed"); return (& $finish) }
            default      { $warnings.Add("SQL admin group: $($g.detail). This run never adds the Support app to it; the database user below is its only standing database right.") }
        }
    } else { $warnings.Add('SQL admin group: not checked (no Microsoft Graph session in this run)') }

    $sid = ConvertTo-PimSupportSqlSid -AppId $SupportAppId
    if ($WhatIfOnly) {
        if ($private) { Write-Host "What if: no firewall rule -- the private server is reached from this machine through its private endpoint" }
        else { Write-Host "What if: open the firewall rule '$rule' on $srv for this machine's public address$(if ("$HostIp".Trim()) { " ($("$HostIp".Trim()))" })$(if ($ruleBefore) { " -- it is already there ($ruleBefore) and would be left as found" }), and remove it at the end" }
        Write-Host "What if: when the database refuses this sign-in and this run is the Invardia Support app's session: make the Invardia Support app the administrator of $srv for the step, then put $(if ($before) { "'$($before['login'])'" } else { 'the administrator' }) back exactly as read"
        Write-Host "What if: in the database $SqlDatabase, install the support access step with consent '$(if ($ConsentLevel) { $ConsentLevel } else { 'as recorded, else troubleshoot' })': the user [$DbUserName] from the Support app's client id (SID $sid) when no user has that id, in $role only (read-only); no database owner role and no SQL admin group membership is given"
        return (& $finish)
    }

    # ---- 3. the firewall rule -------------------------------------------------------------------------------------
    if ($private) { }    # reached through the private endpoint: no rule (decided above)
    elseif (-not $ruleBefore) {
        try {
            [void](& $Arm 'PUT' "$srvPath/firewallRules/$rule`?api-version=$api" @{ properties = @{ startIpAddress = $ip; endIpAddress = $ip } })
            $res.ruleOpened = $true
            if ((& $ruleIp) -ne $ip) { throw "the rule did not read back for $ip" }
            & $say "opened: firewall rule '$rule' = $ip on $srv (read back; removed again at the end)" 'Yellow'
            if ($FirewallWaitSeconds -gt 0) { & $Sleep $FirewallWaitSeconds }
        } catch { $problems.Add("the firewall rule '$rule' could not be opened: $(& $first $_)") }
    } else { & $say "firewall rule '$rule' ($ruleBefore) was already there -- used and left exactly as found" 'DarkGray' }

    # the support access step needs a database OWNER sign-in (it creates a role, signs procedures): this session's own right
    $ownerSql = "SELECT CASE WHEN IS_ROLEMEMBER(N'db_owner') = 1 OR USER_NAME() = N'dbo' THEN 1 ELSE 0 END"
    try {
        if (-not $problems.Count) {
            try {
                # ---- 4. a database sign-in as this session; the Support app as administrator for the step when refused
                $direct = $false; $why = ''
                try { $direct = ("$(& $Sql $ownerSql)".Trim() -eq '1'); if (-not $direct) { $why = "this sign-in is not a database owner in $SqlDatabase" } }
                catch { $direct = $false; $why = & $first $_ }
                if ($direct) { & $say "database sign-in: accepted with the database owner right -- the server's administrator is not touched" 'Green' }
                elseif (-not $SessionIsSupportApp) {
                    $problems.Add("the database refused this sign-in ($why). Sign in as a member of '$SqlAdminGroupName' (or the server's administrator), or have Invardia support run this script in its Support session. The server's administrator was not touched.")
                } elseif (-not $before) {
                    $problems.Add("the database refused the sign-in ($why) and the server's Entra administrator could not be read in full -- it could not be put back afterwards, so it is not changed.")
                } else {
                    $swapLogin = if ($res.group -and "$($res.group.spName)".Trim()) { "$($res.group.spName)".Trim() } else { 'Invardia Support' }
                    $swap = [ordered]@{ administratorType = 'ActiveDirectory'; principalType = 'Application'; login = $swapLogin; sid = "$SupportAppId".Trim().ToLowerInvariant(); tenantId = "$TenantId".Trim().ToLowerInvariant() }
                    if ($null -ne $adOnlyBefore) { $swap['azureADOnlyAuthentication'] = [bool]$adOnlyBefore } elseif ($before.Contains('azureADOnlyAuthentication')) { $swap['azureADOnlyAuthentication'] = [bool]$before['azureADOnlyAuthentication'] }
                    & $say "the database refused the sign-in ($why) -- making the Invardia Support app the administrator of $srv FOR THIS STEP (was '$($before['login'])')" 'Yellow'
                    $res.swapped = $true     # set BEFORE the call: a call that fails half-way is still put back
                    [void](& $Arm 'PATCH' "$srvPath`?api-version=$api" @{ properties = @{ administrators = $swap } })
                    $tries = [Math]::Max(1, [int][Math]::Ceiling($SignInWaitSeconds / [double][Math]::Max(1, $PollSeconds)))
                    $in = $false; $last = ''
                    for ($i = 1; $i -le $tries; $i++) {
                        try { [void](& $Sql 'SELECT 1'); $in = $true; break } catch { $last = & $first $_ }
                        & $Sleep $PollSeconds
                    }
                    if ($in) { & $say 'database sign-in as the Invardia Support app: accepted' 'Green' }
                    else { $problems.Add("the database did not accept the Invardia Support app's sign-in within $SignInWaitSeconds seconds ($last) -- the user was not created. Run the script again in a few minutes.") }
                }
                # ---- 5. the read-only user (OPEN-01): the support access step, read back; an earlier db_owner is REPORTED
                if (-not $problems.Count) {
                    $u = Invoke-PimSupportSqlReadOnlyUser -Sql $Sql -AppId $SupportAppId -DbUserName $DbUserName -ConsentLevel $ConsentLevel -SetBy 'Grant-PimSupportSqlAccess (existing installation)'
                    $res.user = $u
                    if ($u.ok) { & $say "database user [$($u.userName)] (the Support app's client id, SID $sid): $(if ($u.created) { 'created' } elseif ($u.existed) { 'was already there' } else { 'in place' }), in $role only (read back); support access consent '$($u.consented)'$(if ($u.consented -eq 'setup') { ' -- admin rights only inside an open support session, at most 8 hours' })" 'Green' }
                    else { $problems.Add("the database user was not put in place: $($u.problem)") }
                    $lt = Get-PimSupportSqlLegacyText -Legacy @($u.legacy) -SessionOpen ([bool]$u.sessionOpen)
                    if ($lt) { $warnings.Add($lt) }
                }
            } catch { $problems.Add("the step stopped: $(& $first $_)") }
            finally {
                # ---- 6a. the administrator back EXACTLY as read, and read back -- also after a failed step
                if ($res.swapped) {
                    $body = @{ properties = @{ administrators = $before } }
                    $sent = $false; $sendErr = ''
                    foreach ($n in 1..3) {
                        try { [void](& $Arm 'PATCH' "$srvPath`?api-version=$api" $body); $sent = $true; break } catch { $sendErr = & $first $_; & $Sleep 5 }
                    }
                    $diff = @('not read back')
                    for ($i = 0; $i -lt [Math]::Max(1, $ReadBackTries); $i++) {
                        try {
                            $nowAdmin = Get-PimSupportSqlAdminSnapshot -Server (& $get $srvPath)
                            $diff = @(Compare-PimSupportSqlAdmin -Want $before -Have $nowAdmin)
                            if (-not $diff.Count -and $null -ne $adOnlyBefore) { $ao = & $adOnly; if ($ao -ne $adOnlyBefore) { $diff = @("Entra-only sign-in is '$ao', was '$adOnlyBefore'") } }
                        } catch { $diff = @("read-back failed: $(& $first $_)") }
                        if (-not $diff.Count) { break }
                        & $Sleep 5
                    }
                    if (-not $diff.Count) { $res.restored = $true; & $say "restored: the administrator of $srv is '$($before['login'])' again, exactly as read (read back)" 'Green' }
                    else {
                        $problems.Add("THE ADMINISTRATOR OF $srv WAS NOT PUT BACK ($($diff -join '; ')$(if (-not $sent) { "; the request failed: $sendErr" })). Put it back by hand NOW: Azure portal > SQL server $srv > Microsoft Entra ID > Set admin: '$($before['login'])' (id $($before['sid']))$(if ($null -ne $adOnlyBefore) { "; 'Support only Microsoft Entra authentication' = $(if ($adOnlyBefore) { 'on' } else { 'off' })" }).")
                    }
                }
            }
            # ---- 7. proof: a NEW database sign-in as the Support app, after the administrator is back
            if ($res.user -and $res.user.ok) {
                if (-not $SessionIsSupportApp) { $res.proof = @{ state = 'not-checked'; detail = 'this run is not the Invardia Support app''s session, so a sign-in as the Support app was not tried; the evidence is the user and its role, read back' } }
                elseif ($res.swapped -and -not $res.restored) { $res.proof = @{ state = 'not-checked'; detail = 'the administrator was not put back, so a sign-in now proves nothing' } }
                else {
                    try { $as = "$(& $Sql 'SELECT USER_NAME()')".Trim(); $res.proof = @{ state = 'proven'; detail = "a new database sign-in as the Invardia Support app answered (database user: $as)" } }
                    catch {
                        $res.proof = @{ state = 'failed'; detail = "a new database sign-in as the Invardia Support app was refused: $(& $first $_)" }
                        $warnings.Add("$($res.proof.detail). The user and its role are in place (read back); a new right can take a few minutes -- run the script again to check.")
                    }
                }
                & $say "proof: $($res.proof.detail)" $(if ($res.proof.state -eq 'proven') { 'Green' } else { 'Yellow' })
            }
        }
    } finally {
        # ---- 6b. the firewall rule this run opened: removed and read back -- also after a failed step
        if ($res.ruleOpened) {
            $left = $rule
            foreach ($n in 1..3) {
                try { try { [void](& $Arm 'DELETE' "$srvPath/firewallRules/$rule`?api-version=$api" $null) } catch { if ("$($_.Exception.Message)" -notmatch '(?i)HTTP 404\b|NotFound') { throw } }; $left = & $ruleIp } catch { $left = "not read: $(& $first $_)" }
                if (-not $left) { break }
                & $Sleep 5
            }
            if (-not $left) { $res.ruleClosed = $true; & $say "closed: firewall rule '$rule' removed from $srv (read back)" 'Green' }
            else { $problems.Add("the firewall rule '$rule' is STILL on $srv ($left) -- this machine keeps network access to the SQL server. Remove it: Azure portal > SQL server $srv > Networking > Firewall rules: delete '$rule'.") }
        }
    }
    try {
        $res.after = @{ admin = (Get-PimSupportSqlAdminSnapshot -Server (& $get $srvPath)); entraOnly = (& $adOnly); rule = (& $ruleIp) }
        & $show 'after: ' $res.after.admin $res.after.entraOnly $res.after.rule
    } catch { $warnings.Add("the state after the run could not be read: $(& $first $_)") }
    return (& $finish)
}

# ===== END inlined helper: _PimSupportSqlAccess.ps1 =====
# ===== BEGIN inlined helper: _PimSupportSqlJob.ps1 =====
<#
.SYNOPSIS
  PIM REQUIREMENTS 100.116, decision (31) -- "a job inside the install": the Invardia Support app's database user on an
  installation whose database is PRIVATE (public network access off), given by a one-time Container Apps job that runs
  INSIDE the installation's own environment. Shared by Invoke-PimSupportSqlAccessJob.ps1 and its offline test.

.DESCRIPTION
  A private database has no route from a setup machine, so Grant-PimSupportSqlAccess.ps1 stops there. Nothing is opened
  for this: no firewall rule, no public access, no jump host. The grant runs where the route already is.

  WHAT RUNS IN THE JOB is not a second implementation. The job's script is BUILT from the functions of
  _PimSupportSqlAccess.ps1 that are loaded in this process (their own text, taken with Get-Command): the SID from the
  client id, the statement (CREATE USER ... WITH SID, never FROM EXTERNAL PROVIDER; the role), the read, the read-back.
  One behaviour, whichever side runs it. The job needs nothing from the image but its token client and its SQL client
  (engine/_shared/PIM-Rest.ps1 + PIM-SqlStore.ps1 -- in every image that has the database setup job), so it works on an
  installation that is on an older version.

  WHICH IDENTITY. The installation already has one identity that may create a database user from inside: the
  user-assigned identity its database setup job (ca-pim-dbinit) signs in with -- the SQL server's administrator, or a
  member of the SQL admin group. The one-time job is given THAT identity (and the image-pull identity the setup job
  uses) and nothing else. No role, no group membership and no permission is given to any identity. When the
  installation has no such job, or its job does not name a user-assigned identity, or its image is pulled with the
  job's own system identity or a password, the run STOPS before anything is changed and says the options.

  Every caller hands in:
    -Arm   { param([string]$Method, [string]$Path, $Body) }   ARM, the path carries its api-version; throws "... HTTP <code> ..."
    -Graph { param([string]$Method, [string]$Path, $Body) }   Microsoft Graph v1.0 (one read: the Support app exists here)
    -Logs  { param([string]$WorkspaceId, [string]$Execution) } the console lines of one execution (Log Analytics); may return none
  Defaults are functions that return a literal (a $script: variable is $null in a child script scope).
  Needs _PimScriptDoc.ps1 and _PimSupportSqlAccess.ps1 loaded first.

  TIME-LIMITED ACCESS (framework SECAUDIT-1a 4b / 4c, PIM SEC-92): in mode grant the job gives the admin role only until
  that time, records the end on the database user (the marker of engine/_shared/PIM-SupportJit.ps1), keeps running, and
  takes the admin role back at that time ON ITS OWN -- no answer from Invardia, no person and no other job is needed for
  the access to end. Every run of the job first SWEEPS: any grant whose end has passed is taken back before anything is
  given. In mode standing (OPEN-01) the job gives the STANDING READ-ONLY access only: the support access step
  (Invoke-PimSupportSqlReadOnlyUser) with the user in pim_support_read -- never db_owner, never the SQL admin group; a
  db_owner an earlier version gave is reported in the result line (legacyOwner), never kept as "in place".
#>
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-SupportJit.ps1 =====
# PIM4EntraPS -- just-in-time support access to the PIM database (framework SECAUDIT-1a item 4c, PIM SEC-92 / SEC-92 ALIGN).
#
# THE MODEL (4c, SI's #1021 design -- one text for every product):
#   * CONSENT, write-protected: [pimsupport].[Consent] holds the Support app's id (its SID is derived from it) and the level
#     the customer consented to (none | troubleshoot | setup -- OPEN-01 v2, from Invardia's consent channel; v1's read /
#     owner are mapped to troubleshoot / setup, never widened). Only an owner-level principal writes it: the schema is dbo's,
#     no product role has DML on it, ALTER on the schema is DENIED to public. Never from the request, never from a table the
#     engine identity can update. The level granted = the LOWER of the requested and the consented level.
#     troubleshoot / setup = the STANDING read-only user in pim_support_read (SELECT on the schemas pim + platform only);
#     setup also = db_owner while a support session is open (at most 8 h); none = no Support database user at all.
#     WHO DECIDES (framework "SUPPORT ACCESS" point 2): the UPDATER, from Invardia's consent channel, and the in-network
#     database job applies it -- never the engine (it only sweeps an ended grant).
#   * MARKERS: [pimsupport].[GrantMarker], ONE row per database per ROLE ADDED, written in the SAME transaction as the role
#     add: role, added, expires (maxUntil, at most 8 h after the open), pre-existing (the role was already held), the grant id.
#     One OPEN marker per user + role (a filtered unique index); a new open moves its end later, never earlier. A table,
#     not an extended property: one row per role, a history that stays after the revoke (RevokedUtc / RevokedBy /
#     LastError / Attempts), and readable by a signed procedure without any right on the user itself.
#   * REVOKE = the markers: ONLY roles whose marker says the grant added them (not pre-existing), THEN the Support app's
#     open sessions in this database are ended. Never a DROP of the user; never the read-only user, the engines' / web /
#     updater users or the admin group.
#   * SIGNED PROCEDURES that take NO principal parameter: usp_SupportGrant (@Level, @Hours, @Reason, @Ticket, @OpenedBy, @UntilUtc),
#     usp_SupportRevoke (@Mode expired | all, @Source) and usp_SupportState (none). Signed by an in-database certificate
#     whose user is a db_owner member, private key removed after signing, ALTER on the procedures and the schema DENIED to
#     public (altering a signed procedure drops its signature anyway). So the engine and the web app -- never db_owner --
#     can sweep (and the engine can grant, 4b) through EXECUTE alone.
#   * INSTALLING them is ONE support-session step per existing install (Get-PimSupportJitInstallBatches, run by an
#     owner-level sign-in: the one-time job's 'install' mode or a database owner's session). The updater cannot.
#   * THE SWEEP (Invoke-PimSupportJitSweep = usp_SupportRevoke @Mode = expired) runs in every place that runs regularly:
#     every run of the grant job, the heartbeat (uplink) job, the hosted Manager. Idempotent; every revoke audited (-Audit);
#     LOUD (Write-Warning + problems) on any failure; a failed revoke stays open and is retried by every sweeper.
#   * Until the step is run on an install, nothing here exists there: the sweep and the state say 'not installed' and
#     today's standing access stays (SECAUDIT-1a item 4).
#
# Nothing here signs in. Every caller hands in -Sql { param([string]$Query) } -- ONE scalar from the PIM database. The
# procedures answer ONE JSON scalar each. The grant job carries these functions word for word
# (_PimSupportSqlJob.ps1 Get-PimSupportSqlJobFunctionNames), so the job, the heartbeat and the Manager run one implementation.
# PS 5.1 + 7 (no ?. / ??; JSON times are read whether ConvertFrom-Json kept them as text (5.1) or made them [datetime] (7)).
Set-StrictMode -Off

function Get-PimSupportJitSchemaName { <# PURE. The schema of the support-access objects (a literal). #> return 'pimsupport' }
# v2 (OPEN-01, Invardia consent channel 2026-11-04): levels none | troubleshoot | setup, the read-only role pim_support_read,
# at most 8 hours, an exact end (@UntilUtc). A new mark re-creates (and re-signs) every procedure of an install on v1.
function Get-PimSupportJitVersionMark { <# PURE. The version line every procedure carries (a literal). #> return 'pim-support-jit v2' }
function Get-PimSupportJitSignerPrefix { <# PURE. The name prefix of the signing certificate (a literal). #> return 'pimsupport_signer' }
function Get-PimSupportJitProcedureNames { <# PURE. The three signed procedures (literals). #> return @('usp_SupportGrant', 'usp_SupportRevoke', 'usp_SupportState') }
function Get-PimSupportJitAdminRole { <# PURE. The role a setup-level grant adds inside an open support session (a literal). #> return 'db_owner' }
# framework "SUPPORT ACCESS" point 1: the standing read role is <product>_support_read -- SELECT on the product schemas only
function Get-PimSupportJitReadOnlyRole { <# PURE. The standing read-only role (a literal). #> return 'pim_support_read' }
function Get-PimSupportJitReadSchemas { <# PURE. The ONLY schemas the read role may SELECT from (literals). #> return @('pim', 'platform') }
function Get-PimSupportJitLegacyReadOnlyRole { <# PURE. The read-only role of v1, taken away by the migration (a literal). #> return 'db_datareader' }
function Get-PimSupportJitDefaultHours { <# PURE. The default length of a grant (a literal). #> return 8 }
function Get-PimSupportJitMaxHours { <# PURE. The longest a grant may run: 8 h from its open (framework point 1, a literal). #> return 8 }
function Get-PimSupportJitNotSetUpText { <# PURE. The plain state of an install without the support-session step (a literal). #> return 'time-limited support access is not set up on this install' }
function Get-PimSupportJitLevels { <# PURE. The consent / request levels, lowest first (literals; Invardia's consent channel). #> return @('none', 'troubleshoot', 'setup') }

function ConvertTo-PimSupportJitLevel {
    <#
      PURE. A level as this module uses it: none | troubleshoot | setup. The v1 words are MAPPED, never widened:
      read -> troubleshoot (read-only), owner -> setup (admin only inside an open support session). Anything else -> ''.
    #>
    param([AllowNull()][string]$Level)
    $l = "$Level".Trim().ToLowerInvariant()
    switch ($l) { 'read' { return 'troubleshoot' } 'owner' { return 'setup' } }
    if ($l -in @(Get-PimSupportJitLevels)) { return $l }
    return ''
}

function Get-PimSupportJitLowerLevel {
    # PURE. The LOWER of two levels (none < troubleshoot < setup; v1 words mapped); anything unknown counts as none. The
    # procedure decides the same.
    param([AllowNull()][string]$Requested, [AllowNull()][string]$Consented)
    $lv = @(Get-PimSupportJitLevels)
    $a = [Array]::IndexOf($lv, (ConvertTo-PimSupportJitLevel $Requested)); $b = [Array]::IndexOf($lv, (ConvertTo-PimSupportJitLevel $Consented))
    if ($a -lt 0 -or $b -lt 0) { return 'none' }
    return $lv[[Math]::Min($a, $b)]
}

function Test-PimSupportJitUserName {
    # PURE. A database user name this file puts into a statement (the same rule as _PimSupportSqlAccess.ps1).
    param([AllowNull()][string]$Name)
    return [bool]("$Name" -match '^[A-Za-z0-9][A-Za-z0-9 ._@-]{0,127}$')
}

function ConvertTo-PimSupportJitText {
    # PURE. Free text for a marker (reason, ticket, who opened it): safe characters only, at most -Max characters.
    param([AllowNull()][string]$Text, [int]$Max = 120)
    $t = (("$Text" -replace '[^A-Za-z0-9 ._@:#/()+,-]', ' ') -replace '\s+', ' ').Trim()
    if ($t.Length -gt $Max) { $t = $t.Substring(0, $Max).Trim() }
    return $t
}

function Format-PimSupportJitUtc {
    # PURE. A time as the heartbeat and the audit carry it: yyyy-MM-ddTHH:mm:ssZ (UTC, invariant culture).
    param([Parameter(Mandatory)][datetime]$Utc)
    return $Utc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture)
}

function ConvertFrom-PimSupportJitUtc {
    # PURE. A time from a procedure's answer -> a UTC [datetime], or $null. Text yyyy-MM-ddTHH:mm:ss[.fff]Z (5.1 keeps the
    # text) or a [datetime] (7's ConvertFrom-Json makes one). Never the local culture, never a guess.
    param([AllowNull()]$Value)
    if ($Value -is [datetime]) { if ($Value.Kind -eq [DateTimeKind]::Unspecified) { return [datetime]::SpecifyKind($Value, [DateTimeKind]::Utc) }; return $Value.ToUniversalTime() }
    $d = [datetime]::MinValue
    $styles = [Globalization.DateTimeStyles]::AssumeUniversal -bor [Globalization.DateTimeStyles]::AdjustToUniversal
    $fmts = [string[]]@('yyyy-MM-ddTHH:mm:ssZ', 'yyyy-MM-ddTHH:mm:ss.fffZ', 'yyyy-MM-ddTHH:mm:ss.fffffffZ')
    if ([datetime]::TryParseExact("$Value".Trim(), $fmts, [Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { return $d }
    return $null
}

function ConvertTo-PimSupportJitSqlText {
    # PURE. A value as an N'...' literal (quotes doubled), or NULL.
    param([AllowNull()][string]$Text)
    if ($null -eq $Text -or "$Text" -eq '') { return 'NULL' }
    return "N'" + "$Text".Replace("'", "''") + "'"
}

# ======================================================================================================== the SQL objects
function Get-PimSupportJitTableSql {
    # PURE. The consent table (one row) and the marker table (one row per role added), dbo's schema. Idempotent.
    $s = Get-PimSupportJitSchemaName
    return @"
IF SCHEMA_ID(N'$s') IS NULL EXEC(N'CREATE SCHEMA [$s] AUTHORIZATION [dbo];');
IF OBJECT_ID(N'[$s].[Consent]') IS NULL
    CREATE TABLE [$s].[Consent] (
        Id           TINYINT          NOT NULL CONSTRAINT PK_PimSupportConsent PRIMARY KEY CONSTRAINT CK_PimSupportConsent_One CHECK (Id = 1),
        SupportAppId UNIQUEIDENTIFIER NOT NULL,
        UserName     SYSNAME          NOT NULL,
        ConsentLevel NVARCHAR(20)     NOT NULL CONSTRAINT CK_PimSupportConsent_Level CHECK (ConsentLevel IN (N'none', N'troubleshoot', N'setup')),
        SetUtc       DATETIME2(0)     NOT NULL,
        SetBy        NVARCHAR(120)    NOT NULL);
IF OBJECT_ID(N'[$s].[GrantMarker]') IS NULL
BEGIN
    CREATE TABLE [$s].[GrantMarker] (
        MarkerId    INT IDENTITY(1, 1) NOT NULL CONSTRAINT PK_PimSupportGrantMarker PRIMARY KEY,
        GrantId     UNIQUEIDENTIFIER   NOT NULL,
        UserSid     VARBINARY(85)      NOT NULL,
        RoleName    SYSNAME            NOT NULL,
        AddedUtc    DATETIME2(0)       NOT NULL,
        ExpiresUtc  DATETIME2(0)       NOT NULL,
        PreExisting BIT                NOT NULL,
        Reason      NVARCHAR(120)      NULL,
        Ticket      NVARCHAR(40)       NULL,
        OpenedBy    NVARCHAR(120)      NULL,
        RevokedUtc  DATETIME2(0)       NULL,
        RevokedBy   NVARCHAR(20)       NULL,
        Attempts    INT                NOT NULL CONSTRAINT DF_PimSupportGrantMarker_Attempts DEFAULT (0),
        LastError   NVARCHAR(400)      NULL);
    CREATE UNIQUE INDEX UX_PimSupportGrantMarker_Open ON [$s].[GrantMarker] (UserSid, RoleName) WHERE RevokedUtc IS NULL;
END
-- MIGRATION v1 -> v2 (OPEN-01): the consent words none | read | owner become none | troubleshoot | setup, MAPPED, never
-- widened (read -> troubleshoot, owner -> setup). The column grows to hold them. Dynamic SQL: the batch compiles on either shape.
IF COL_LENGTH(N'[$s].[Consent]', N'ConsentLevel') < 40
BEGIN
    IF OBJECT_ID(N'[$s].[CK_PimSupportConsent_Level]', N'C') IS NOT NULL EXEC(N'ALTER TABLE [$s].[Consent] DROP CONSTRAINT [CK_PimSupportConsent_Level];');
    EXEC(N'ALTER TABLE [$s].[Consent] ALTER COLUMN ConsentLevel NVARCHAR(20) NOT NULL;');
    EXEC(N'UPDATE [$s].[Consent] SET ConsentLevel = CASE ConsentLevel WHEN N''read'' THEN N''troubleshoot'' WHEN N''owner'' THEN N''setup'' WHEN N''troubleshoot'' THEN N''troubleshoot'' WHEN N''setup'' THEN N''setup'' ELSE N''none'' END;');
    EXEC(N'ALTER TABLE [$s].[Consent] ADD CONSTRAINT [CK_PimSupportConsent_Level] CHECK (ConsentLevel IN (N''none'', N''troubleshoot'', N''setup''));');
END
"@
}

function Get-PimSupportJitReadRoleSql {
    <#
      PURE. The standing read role (framework "SUPPORT ACCESS" point 1): pim_support_read, owned by dbo, SELECT on the
      product schemas pim + platform and NOTHING else (a right it holds on anything else is taken back). Idempotent; run
      only by the support-session step (an owner-level sign-in) -- never by the engine or the updater.
    #>
    $r = Get-PimSupportJitReadOnlyRole
    $l = New-Object System.Collections.Generic.List[string]
    $l.Add("IF DATABASE_PRINCIPAL_ID(N'$r') IS NULL EXEC(N'CREATE ROLE [$r] AUTHORIZATION [dbo];');")
    foreach ($sc in @(Get-PimSupportJitReadSchemas)) {
        $l.Add("IF SCHEMA_ID(N'$sc') IS NOT NULL AND NOT EXISTS (SELECT 1 FROM sys.database_permissions WHERE class = 3 AND major_id = SCHEMA_ID(N'$sc') AND grantee_principal_id = DATABASE_PRINCIPAL_ID(N'$r') AND permission_name = N'SELECT' AND state = 'G') EXEC(N'GRANT SELECT ON SCHEMA::[$sc] TO [$r];');")
    }
    $in = (@(Get-PimSupportJitReadSchemas) | ForEach-Object { "N'$_'" }) -join ', '
    $l.Add(@"
-- nothing else: any other right the role holds is taken back (class 0 database, 1 object, 3 schema)
DECLARE @x NVARCHAR(400), @t NVARCHAR(400);
DECLARE p CURSOR LOCAL FAST_FORWARD FOR
    SELECT CASE dp.class WHEN 0 THEN N'' WHEN 1 THEN N' ON OBJECT::' + QUOTENAME(OBJECT_SCHEMA_NAME(dp.major_id)) + N'.' + QUOTENAME(OBJECT_NAME(dp.major_id))
                         WHEN 3 THEN N' ON SCHEMA::' + QUOTENAME(SCHEMA_NAME(dp.major_id)) END, dp.permission_name
      FROM sys.database_permissions dp
     WHERE dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'$r') AND dp.class IN (0, 1, 3) AND dp.permission_name <> N'CONNECT'
       AND NOT (dp.class = 3 AND dp.permission_name = N'SELECT' AND dp.state = 'G' AND SCHEMA_NAME(dp.major_id) IN ($in));
OPEN p; FETCH NEXT FROM p INTO @t, @x;
WHILE @@FETCH_STATUS = 0
BEGIN
    SET @x = N'REVOKE ' + @x + @t + N' FROM [$r];'; EXEC sys.sp_executesql @x;
    FETCH NEXT FROM p INTO @t, @x;
END
CLOSE p; DEALLOCATE p;
"@)
    return ($l -join "`n")
}

function Get-PimSupportJitProcedureText {
    <#
      PURE. The three procedures. NO principal parameter: the Support app comes from [Consent]. Every rule is checked INSIDE
      (a signed module never trusts its caller); names are QUOTENAME'd; each answers ONE JSON scalar.
    #>
    param([Parameter(Mandatory)][ValidateSet('usp_SupportGrant', 'usp_SupportRevoke', 'usp_SupportState')][string]$Name)
    $s = Get-PimSupportJitSchemaName; $m = Get-PimSupportJitVersionMark
    $t = @{}
    $t['usp_SupportGrant'] = @"
CREATE OR ALTER PROCEDURE [$s].[usp_SupportGrant]
    @Level    NVARCHAR(20),
    @Hours    INT,
    @Reason   NVARCHAR(120) = NULL,
    @Ticket   NVARCHAR(40)  = NULL,
    @OpenedBy NVARCHAR(120) = NULL,
    @UntilUtc DATETIME2(0)  = NULL
AS
BEGIN
    -- $m -- framework SECAUDIT-1a 4c + "SUPPORT ACCESS" points 1-2. NO principal parameter: the Support app and its
    -- consented level come from [$s].[Consent] (written only by the support-session step, from Invardia's answer).
    -- troubleshoot = the STANDING read-only user (pim_support_read) only; setup = that + db_owner until the end, at most
    -- 8 h after the open -- never longer, also when an open grant is extended.
    SET NOCOUNT ON; SET XACT_ABORT ON;
    DECLARE @app UNIQUEIDENTIFIER, @user SYSNAME, @consent NVARCHAR(20), @sid VARBINARY(16), @granted NVARCHAR(20),
            @now DATETIME2(0) = SYSUTCDATETIME(), @until DATETIME2(0), @grant UNIQUEIDENTIFIER = NEWID(), @s NVARCHAR(400),
            @pre BIT, @added INT = 0, @extended INT = 0;
    SELECT @app = SupportAppId, @user = UserName, @consent = ConsentLevel FROM [$s].[Consent] WHERE Id = 1;
    IF @app IS NULL OR @consent IS NULL OR @consent NOT IN (N'troubleshoot', N'setup')
        THROW 51101, N'usp_SupportGrant: no consent to support access is recorded in this database.', 1;
    IF @Level IS NULL OR @Level NOT IN (N'troubleshoot', N'setup') THROW 51102, N'usp_SupportGrant: the level must be troubleshoot or setup.', 1;
    IF @Hours IS NULL OR @Hours < 1 OR @Hours > 8 THROW 51103, N'usp_SupportGrant: the hours must be 1 to 8.', 1;
    IF DATABASE_PRINCIPAL_ID(N'pim_support_read') IS NULL THROW 51105, N'usp_SupportGrant: the read role pim_support_read is missing -- run the support-session step.', 1;
    -- the LOWER of the requested and the consented level
    SET @granted = CASE WHEN @Level = N'setup' AND @consent = N'setup' THEN N'setup' ELSE N'troubleshoot' END;
    SET @until = DATEADD(HOUR, @Hours, @now);
    IF @UntilUtc IS NOT NULL
    BEGIN
        IF @UntilUtc <= @now THROW 51106, N'usp_SupportGrant: the end lies in the past.', 1;
        IF @UntilUtc < @until SET @until = @UntilUtc;
    END
    SET @sid = CAST(@app AS VARBINARY(16));
    -- the STANDING read-only user first (4a: it exists before any admin right is given)
    IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE sid = @sid)
    BEGIN
        IF EXISTS (SELECT 1 FROM sys.database_principals WHERE name = @user)
            THROW 51104, N'usp_SupportGrant: another principal already has the Support user''s name -- an owner must resolve it.', 1;
        SET @s = N'CREATE USER ' + QUOTENAME(@user) + N' WITH SID = ' + CONVERT(NVARCHAR(40), @sid, 1) + N', TYPE = E;';
        EXEC sys.sp_executesql @s;
    END
    SELECT @user = name FROM sys.database_principals WHERE sid = @sid;
    IF ISNULL(IS_ROLEMEMBER(N'pim_support_read', @user), 0) = 0
    BEGIN SET @s = N'ALTER ROLE [pim_support_read] ADD MEMBER ' + QUOTENAME(@user) + N';'; EXEC sys.sp_executesql @s; END
    IF @granted = N'setup'
    BEGIN
        -- ONE marker per role added, in the SAME transaction as the role add; a new open extends the open marker -- to at
        -- most 8 h after that marker was opened
        BEGIN TRANSACTION;
        IF EXISTS (SELECT 1 FROM [$s].[GrantMarker] WITH (UPDLOCK, HOLDLOCK) WHERE UserSid = @sid AND RoleName = N'db_owner' AND RevokedUtc IS NULL)
        BEGIN
            SELECT @grant = GrantId, @pre = PreExisting FROM [$s].[GrantMarker] WHERE UserSid = @sid AND RoleName = N'db_owner' AND RevokedUtc IS NULL;
            UPDATE [$s].[GrantMarker]
               SET ExpiresUtc = CASE WHEN (CASE WHEN ExpiresUtc > @until THEN ExpiresUtc ELSE @until END) > DATEADD(HOUR, 8, AddedUtc)
                                     THEN DATEADD(HOUR, 8, AddedUtc) ELSE (CASE WHEN ExpiresUtc > @until THEN ExpiresUtc ELSE @until END) END
             WHERE UserSid = @sid AND RoleName = N'db_owner' AND RevokedUtc IS NULL;
            IF @pre = 0 AND IS_ROLEMEMBER(N'db_owner', @user) = 0
            BEGIN SET @s = N'ALTER ROLE [db_owner] ADD MEMBER ' + QUOTENAME(@user) + N';'; EXEC sys.sp_executesql @s; SET @added = 1; END
            SET @extended = 1;
        END
        ELSE
        BEGIN
            SET @pre = CASE WHEN IS_ROLEMEMBER(N'db_owner', @user) = 1 THEN 1 ELSE 0 END;
            INSERT INTO [$s].[GrantMarker] (GrantId, UserSid, RoleName, AddedUtc, ExpiresUtc, PreExisting, Reason, Ticket, OpenedBy)
                VALUES (@grant, @sid, N'db_owner', @now, @until, @pre, LEFT(@Reason, 120), LEFT(@Ticket, 40), LEFT(@OpenedBy, 120));
            IF @pre = 0
            BEGIN SET @s = N'ALTER ROLE [db_owner] ADD MEMBER ' + QUOTENAME(@user) + N';'; EXEC sys.sp_executesql @s; SET @added = 1; END
        END
        COMMIT TRANSACTION;
    END
    SELECT (SELECT CASE WHEN @granted = N'setup' THEN @grant END AS grantId, @granted AS level, @Level AS requested, @consent AS consented,
                   @user AS userName, @added AS rolesAdded, @extended AS extended, ISNULL(@pre, 0) AS preExisting,
                   CONVERT(NVARCHAR(20), (SELECT MAX(ExpiresUtc) FROM [$s].[GrantMarker] WHERE UserSid = @sid AND RevokedUtc IS NULL), 126) + N'Z' AS untilUtc,
                   CASE WHEN IS_ROLEMEMBER(N'pim_support_read', @user) = 1 THEN 1 ELSE 0 END AS readOnly,
                   CASE WHEN IS_ROLEMEMBER(N'db_owner', @user) = 1 THEN 1 ELSE 0 END AS inOwner
            FOR JSON PATH, WITHOUT_ARRAY_WRAPPER) AS result;
END
"@
    $t['usp_SupportRevoke'] = @"
CREATE OR ALTER PROCEDURE [$s].[usp_SupportRevoke]
    @Mode   NVARCHAR(10),
    @Source NVARCHAR(20) = NULL
AS
BEGIN
    -- $m -- framework SECAUDIT-1a 4c. NO principal parameter: only the users the open markers name are touched.
    SET NOCOUNT ON;
    IF @Mode IS NULL OR @Mode NOT IN (N'expired', N'all') THROW 51111, N'usp_SupportRevoke: the mode must be expired or all.', 1;
    DECLARE @now DATETIME2(0) = SYSUTCDATETIME(), @id INT, @sid VARBINARY(85), @role SYSNAME, @pre BIT, @user SYSNAME,
            @s NVARCHAR(400), @err NVARCHAR(400), @spid INT, @ended INT = 0;
    DECLARE @done TABLE (MarkerId INT, GrantId UNIQUEIDENTIFIER, RoleName SYSNAME, UserName SYSNAME NULL, ExpiresUtc DATETIME2(0),
                         PreExisting BIT, Removed BIT, Error NVARCHAR(400) NULL);
    DECLARE @sids TABLE (UserSid VARBINARY(85) PRIMARY KEY);
    DECLARE m CURSOR LOCAL FAST_FORWARD FOR
        SELECT MarkerId, UserSid, RoleName, PreExisting FROM [$s].[GrantMarker]
         WHERE RevokedUtc IS NULL AND (@Mode = N'all' OR ExpiresUtc <= @now);
    OPEN m; FETCH NEXT FROM m INTO @id, @sid, @role, @pre;
    WHILE @@FETCH_STATUS = 0
    BEGIN
        SET @user = (SELECT name FROM sys.database_principals WHERE sid = @sid); SET @err = NULL;
        BEGIN TRY
            BEGIN TRANSACTION;
            -- ONLY a role the grant ADDED (not pre-existing), and only the role the marker names
            IF @pre = 0 AND @user IS NOT NULL AND @role = N'db_owner' AND IS_ROLEMEMBER(@role, @user) = 1
            BEGIN SET @s = N'ALTER ROLE ' + QUOTENAME(@role) + N' DROP MEMBER ' + QUOTENAME(@user) + N';'; EXEC sys.sp_executesql @s; END
            UPDATE [$s].[GrantMarker] SET RevokedUtc = @now, RevokedBy = LEFT(ISNULL(@Source, N'unknown'), 20), Attempts = Attempts + 1, LastError = NULL
             WHERE MarkerId = @id;
            COMMIT TRANSACTION;
            IF NOT EXISTS (SELECT 1 FROM @sids WHERE UserSid = @sid) INSERT INTO @sids (UserSid) VALUES (@sid);
        END TRY
        BEGIN CATCH
            IF @@TRANCOUNT > 0 ROLLBACK TRANSACTION;
            SET @err = LEFT(ERROR_MESSAGE(), 400);
            UPDATE [$s].[GrantMarker] SET Attempts = Attempts + 1, LastError = @err WHERE MarkerId = @id;
        END CATCH
        INSERT INTO @done (MarkerId, GrantId, RoleName, UserName, ExpiresUtc, PreExisting, Removed, Error)
            SELECT MarkerId, GrantId, RoleName, @user, ExpiresUtc, PreExisting, CASE WHEN @err IS NULL AND @pre = 0 THEN 1 ELSE 0 END, @err
              FROM [$s].[GrantMarker] WHERE MarkerId = @id;
        FETCH NEXT FROM m INTO @id, @sid, @role, @pre;
    END
    CLOSE m; DEALLOCATE m;
    -- THEN end the Support app's open sessions in this database: a session opened before the end never keeps the right.
    -- Whether this signature may SEE other sessions is said, not assumed: Azure SQL Database shows the database's sessions
    -- with VIEW DATABASE STATE (db_owner has it); a SQL Server instance only with VIEW SERVER STATE (a server right). A
    -- session that could not be ended, or sessions that could not be seen, are reported -- never silently "0 ended".
    DECLARE @canSee BIT = CASE WHEN EXISTS (SELECT 1 FROM fn_my_permissions(NULL, N'SERVER') WHERE permission_name = N'VIEW SERVER STATE')
                                 OR (CONVERT(INT, SERVERPROPERTY('EngineEdition')) IN (5, 8) AND EXISTS (SELECT 1 FROM fn_my_permissions(NULL, N'DATABASE') WHERE permission_name = N'VIEW DATABASE STATE'))
                               THEN 1 ELSE 0 END;
    DECLARE @notEnded INT = 0, @killErr NVARCHAR(400) = NULL, @lg NVARCHAR(256), @olg NVARCHAR(256);
    DECLARE @killed TABLE (SessionId INT, LoginName NVARCHAR(256), OriginalLogin NVARCHAR(256));
    DECLARE k CURSOR LOCAL FAST_FORWARD FOR
        SELECT es.session_id, es.login_name, es.original_login_name FROM sys.dm_exec_sessions es
         WHERE es.session_id <> @@SPID AND es.is_user_process = 1
           AND EXISTS (SELECT 1 FROM @sids x WHERE x.UserSid = es.original_security_id OR x.UserSid = es.security_id);
    OPEN k; FETCH NEXT FROM k INTO @spid, @lg, @olg;
    WHILE @@FETCH_STATUS = 0
    BEGIN
        BEGIN TRY SET @s = N'KILL ' + CAST(@spid AS NVARCHAR(10)) + N';'; EXEC (@s); SET @ended = @ended + 1; INSERT INTO @killed VALUES (@spid, @lg, @olg); END TRY
        BEGIN CATCH SET @notEnded = @notEnded + 1; SET @killErr = LEFT(ERROR_MESSAGE(), 400); END CATCH
        FETCH NEXT FROM k INTO @spid, @lg, @olg;
    END
    CLOSE k; DEALLOCATE k;
    SELECT (SELECT @Mode AS mode, (SELECT COUNT(*) FROM @done) AS found, @ended AS sessionsEnded, @notEnded AS sessionsNotEnded,
                   @canSee AS sessionsChecked, @killErr AS sessionError,
                   (SELECT SessionId AS id, LoginName AS login, OriginalLogin AS originalLogin FROM @killed FOR JSON PATH) AS endedSessions,
                   (SELECT GrantId AS grantId, RoleName AS role, UserName AS userName, CONVERT(NVARCHAR(20), ExpiresUtc, 126) + N'Z' AS expiresUtc,
                           PreExisting AS preExisting, Removed AS removed FROM @done WHERE Error IS NULL FOR JSON PATH) AS revoked,
                   (SELECT GrantId AS grantId, RoleName AS role, UserName AS userName, CONVERT(NVARCHAR(20), ExpiresUtc, 126) + N'Z' AS expiresUtc,
                           Error AS error FROM @done WHERE Error IS NOT NULL FOR JSON PATH) AS failed,
                   (SELECT RoleName AS role, CONVERT(NVARCHAR(20), ExpiresUtc, 126) + N'Z' AS expiresUtc FROM [$s].[GrantMarker]
                     WHERE RevokedUtc IS NULL FOR JSON PATH) AS [open]
            FOR JSON PATH, WITHOUT_ARRAY_WRAPPER) AS result;
END
"@
    $t['usp_SupportState'] = @"
CREATE OR ALTER PROCEDURE [$s].[usp_SupportState]
AS
BEGIN
    -- $m -- framework SECAUDIT-1a 4c. Read-only. NO parameter at all.
    SET NOCOUNT ON;
    DECLARE @app UNIQUEIDENTIFIER, @consent NVARCHAR(20), @sid VARBINARY(16), @user SYSNAME;
    SELECT @app = SupportAppId, @consent = ConsentLevel FROM [$s].[Consent] WHERE Id = 1;
    IF @app IS NOT NULL BEGIN SET @sid = CAST(@app AS VARBINARY(16)); SELECT @user = name FROM sys.database_principals WHERE sid = @sid; END
    -- v2: readOnly = the standing read role pim_support_read; appId + userExists (does the Support user exist at all) and
    -- legacyReader (still in v1's db_datareader) let the updater decide from facts, never from a guess.
    SELECT (SELECT ISNULL(@consent, N'none') AS consented,
                   CONVERT(NVARCHAR(36), @app) AS appId,
                   CASE WHEN @user IS NOT NULL THEN 1 ELSE 0 END AS userExists,
                   CASE WHEN @user IS NOT NULL AND IS_ROLEMEMBER(N'pim_support_read', @user) = 1 THEN 1 ELSE 0 END AS readOnly,
                   CASE WHEN @user IS NOT NULL AND IS_ROLEMEMBER(N'db_datareader', @user) = 1 THEN 1 ELSE 0 END AS legacyReader,
                   CASE WHEN @user IS NOT NULL AND IS_ROLEMEMBER(N'db_owner', @user) = 1 THEN 1 ELSE 0 END AS inOwner,
                   (SELECT COUNT(*) FROM [$s].[GrantMarker] WHERE RevokedUtc IS NULL) AS openMarkers,
                   (SELECT COUNT(*) FROM [$s].[GrantMarker] WHERE RevokedUtc IS NULL AND ExpiresUtc <= SYSUTCDATETIME()) AS expiredOpen,
                   (SELECT COUNT(*) FROM [$s].[GrantMarker] mk WHERE mk.RevokedUtc IS NULL AND mk.PreExisting = 0
                       AND NOT EXISTS (SELECT 1 FROM sys.database_role_members rm JOIN sys.database_principals r ON r.principal_id = rm.role_principal_id
                                       JOIN sys.database_principals p ON p.principal_id = rm.member_principal_id WHERE r.name = mk.RoleName AND p.sid = mk.UserSid)) AS halfDone,
                   CONVERT(NVARCHAR(20), (SELECT MAX(ExpiresUtc) FROM [$s].[GrantMarker] WHERE RevokedUtc IS NULL), 126) + N'Z' AS jitUntil,
                   CONVERT(NVARCHAR(20), (SELECT MIN(AddedUtc) FROM [$s].[GrantMarker] WHERE RevokedUtc IS NULL), 126) + N'Z' AS jitOpenedUtc,
                   (SELECT COUNT(*) FROM [$s].[GrantMarker] WHERE AddedUtc >= DATEADD(HOUR, -24, SYSUTCDATETIME())) AS opened24h,
                   (SELECT COUNT(*) FROM [$s].[GrantMarker] WHERE RevokedUtc >= DATEADD(HOUR, -24, SYSUTCDATETIME())) AS closed24h,
                   -- real SQL (test VM 2026-11-02): the schema deny does not stop a DDL-admin member from making a NEW object in this
                   -- schema. Such an object is never signed and nobody may run it -- but it is REPORTED, never left unseen.
                   (SELECT COUNT(*) FROM sys.objects o WHERE o.schema_id = SCHEMA_ID(N'$s') AND o.type IN ('U', 'V', 'P', 'PC', 'FN', 'IF', 'TF', 'TR', 'SN')
                       AND o.name NOT IN (N'Consent', N'GrantMarker', N'usp_SupportGrant', N'usp_SupportRevoke', N'usp_SupportState')) AS foreignObjects
            FOR JSON PATH, WITHOUT_ARRAY_WRAPPER) AS result;
END
"@
    return $t[$Name]
}

function Get-PimSupportJitInstallBatches {
    <#
      PURE. THE SUPPORT-SESSION STEP (4c: one per existing install; the updater cannot), run by an OWNER-LEVEL sign-in.
      Idempotent. Batches, in order:
        1 the schema + the two tables
        2 the consent (the customer's level for this Support app), written here and nowhere else
        3 the STANDING read-only user of the Support app (4a: before any admin right is made just-in-time)
        4 the three procedures (only when missing or another version -- re-creating one drops its signature)
        5 SIGN when any is unsigned: earlier signers out, a NEW certificate (random password made inside SQL, never
          returned), its user a db_owner member, ADD SIGNATURE to all three, the private key REMOVED
        6 ALTER on the procedures and on the schema DENIED to public; EXECUTE for the engine role (revoke, state: the
          heartbeat sweeps), the web role (revoke, state: the Manager sweeps) and the updater role (state: it decides from
          Invardia's consent channel). v2 (OPEN-01): the ENGINE no longer opens anything -- its EXECUTE on the grant
          procedure is taken back; only this owner-level job path opens (framework "SUPPORT ACCESS" point 2).
      v2 (OPEN-01): the read role pim_support_read (SELECT on pim + platform, nothing else) is made in batch 1; a v1 consent
      (read / owner) is MAPPED to troubleshoot / setup, never widened, and the v1 read-only role db_datareader is taken away
      from the Support user once it is in pim_support_read. Consent none: every open grant is closed (the signed revoke)
      and the Support user is REMOVED (no Support database user at all).
    #>
    param([Parameter(Mandatory)][string]$SupportAppId, [Parameter(Mandatory)][ValidateSet('none', 'troubleshoot', 'setup', 'read', 'owner')][string]$ConsentLevel,
          [string]$UserName = 'invardia-support', [string]$SetBy = '')
    $g = [guid]::Empty
    if (-not [guid]::TryParse("$SupportAppId".Trim(), [ref]$g) -or $g -eq [guid]::Empty) { throw "Get-PimSupportJitInstallBatches: '$SupportAppId' is not an application (client) id." }
    if (-not (Test-PimSupportJitUserName -Name $UserName)) { throw "Get-PimSupportJitInstallBatches: '$UserName' is not a safe database user name." }
    $ConsentLevel = ConvertTo-PimSupportJitLevel $ConsentLevel
    $s = Get-PimSupportJitSchemaName; $m = Get-PimSupportJitVersionMark; $pfx = Get-PimSupportJitSignerPrefix
    $ro = Get-PimSupportJitReadOnlyRole; $legacy = Get-PimSupportJitLegacyReadOnlyRole
    $procs = @(Get-PimSupportJitProcedureNames)
    $b = New-Object System.Collections.Generic.List[string]
    [void]$b.Add((Get-PimSupportJitTableSql) + "`n" + (Get-PimSupportJitReadRoleSql))
    $by = ConvertTo-PimSupportJitSqlText -Text (ConvertTo-PimSupportJitText -Text $SetBy -Max 120)
    if ($by -eq 'NULL') { $by = "N'support-session step'" }
    [void]$b.Add(@"
MERGE [$s].[Consent] AS t
USING (SELECT CAST(1 AS TINYINT) AS Id, CAST('$g' AS UNIQUEIDENTIFIER) AS SupportAppId, $(ConvertTo-PimSupportJitSqlText -Text $UserName) AS UserName, N'$ConsentLevel' AS ConsentLevel) AS v ON t.Id = v.Id
WHEN MATCHED THEN UPDATE SET SupportAppId = v.SupportAppId, UserName = v.UserName, ConsentLevel = v.ConsentLevel, SetUtc = SYSUTCDATETIME(), SetBy = $by
WHEN NOT MATCHED THEN INSERT (Id, SupportAppId, UserName, ConsentLevel, SetUtc, SetBy) VALUES (v.Id, v.SupportAppId, v.UserName, v.ConsentLevel, SYSUTCDATETIME(), $by);
"@)
    if ($ConsentLevel -ne 'none') {
        $q = '[' + "$UserName".Replace(']', ']]') + ']'
        [void]$b.Add(@"
-- [pimsupport] the Support app's STANDING read-only user (4a: before any admin right is made just-in-time)
DECLARE @sid VARBINARY(16) = CAST(CAST('$g' AS UNIQUEIDENTIFIER) AS VARBINARY(16)), @n SYSNAME, @q NVARCHAR(400);
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE sid = @sid)
    CREATE USER $q WITH SID = 0x$((@($g.ToByteArray()) | ForEach-Object { $_.ToString('X2') }) -join ''), TYPE = E;
SELECT @n = name FROM sys.database_principals WHERE sid = @sid;
IF @n IS NOT NULL AND ISNULL(IS_ROLEMEMBER(N'$ro', @n), 0) = 0 BEGIN SET @q = N'ALTER ROLE [$ro] ADD MEMBER ' + QUOTENAME(@n) + N';'; EXEC sys.sp_executesql @q; END
-- MIGRATION v1 -> v2: the broad v1 read role goes once the narrow one is in place (never widened)
IF @n IS NOT NULL AND IS_ROLEMEMBER(N'$ro', @n) = 1 AND IS_ROLEMEMBER(N'$legacy', @n) = 1 BEGIN SET @q = N'ALTER ROLE [$legacy] DROP MEMBER ' + QUOTENAME(@n) + N';'; EXEC sys.sp_executesql @q; END
"@)
    }
    foreach ($p in $procs) {
        $txt = (Get-PimSupportJitProcedureText -Name $p).Replace("'", "''")
        [void]$b.Add(@"
IF OBJECT_ID(N'[$s].[$p]') IS NULL OR ISNULL(OBJECT_DEFINITION(OBJECT_ID(N'[$s].[$p]')), N'') NOT LIKE N'%$m%'
    EXEC sys.sp_executesql N'$txt';
"@)
    }
    $unsigned = @($procs | ForEach-Object { "NOT EXISTS (SELECT 1 FROM sys.crypt_properties cp JOIN sys.certificates c ON c.thumbprint = cp.thumbprint WHERE cp.major_id = OBJECT_ID(N'[$s].[$_]') AND c.name LIKE N'$pfx%')" }) -join "`n   OR "
    $signLines = @($procs | ForEach-Object { "    SET @s = N'ADD SIGNATURE TO [$s].[$_] BY CERTIFICATE ' + QUOTENAME(@cert) + N' WITH PASSWORD = ' + QUOTENAME(@pw, '''') + N';'; EXEC sys.sp_executesql @s;" }) -join "`n"
    [void]$b.Add(@"
IF $unsigned
BEGIN
    DECLARE @old SYSNAME, @s NVARCHAR(MAX);
    DECLARE oldc CURSOR LOCAL FAST_FORWARD FOR SELECT name FROM sys.certificates WHERE name LIKE N'$pfx%';
    OPEN oldc; FETCH NEXT FROM oldc INTO @old;
    WHILE @@FETCH_STATUS = 0
    BEGIN
        -- an EARLIER signer of these procedures only (its certificate name): its user leaves db_owner and goes with it
        IF DATABASE_PRINCIPAL_ID(@old) IS NOT NULL
        BEGIN
            IF IS_ROLEMEMBER(N'db_owner', @old) = 1 BEGIN SET @s = N'ALTER ROLE [db_owner] DROP MEMBER ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @s; END
            SET @s = N'DROP USER ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @s;
        END
        SET @s = N'DROP CERTIFICATE ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @s;
        FETCH NEXT FROM oldc INTO @old;
    END
    CLOSE oldc; DEALLOCATE oldc;
    DECLARE @cert SYSNAME = N'${pfx}_' + FORMAT(SYSUTCDATETIME(), 'yyyyMMddHHmmss');
    DECLARE @pw NVARCHAR(200) = CONVERT(NVARCHAR(36), NEWID()) + N'Pa1!' + CONVERT(NVARCHAR(36), NEWID());
    SET @s = N'CREATE CERTIFICATE ' + QUOTENAME(@cert) + N' ENCRYPTION BY PASSWORD = ' + QUOTENAME(@pw, '''')
           + N' WITH SUBJECT = ''PIM Manager support access procedure signer'', EXPIRY_DATE = ''20991231'';';
    EXEC sys.sp_executesql @s;
    SET @s = N'CREATE USER ' + QUOTENAME(@cert) + N' FROM CERTIFICATE ' + QUOTENAME(@cert) + N';'; EXEC sys.sp_executesql @s;
    SET @s = N'ALTER ROLE [db_owner] ADD MEMBER ' + QUOTENAME(@cert) + N';'; EXEC sys.sp_executesql @s;
$signLines
    SET @s = N'ALTER CERTIFICATE ' + QUOTENAME(@cert) + N' REMOVE PRIVATE KEY;'; EXEC sys.sp_executesql @s;
END
"@)
    $deny = @($procs + @('Consent', 'GrantMarker') | ForEach-Object { "DENY ALTER ON OBJECT::[$s].[$_] TO [public];" }) + @("DENY ALTER ON SCHEMA::[$s] TO [public];")
    $exec = @(
        @('pim_engine', 'usp_SupportRevoke'), @('pim_engine', 'usp_SupportState'),
        @('pim_web', 'usp_SupportRevoke'), @('pim_web', 'usp_SupportState'),
        @('pim_updater', 'usp_SupportState')
    ) | ForEach-Object { "IF DATABASE_PRINCIPAL_ID(N'$($_[0])') IS NOT NULL GRANT EXECUTE ON OBJECT::[$s].[$($_[1])] TO [$($_[0])];" }
    # v2: the engine never opens anything (framework "SUPPORT ACCESS" point 2) -- a v1 grant of EXECUTE on the open is taken back
    $unexec = @("IF DATABASE_PRINCIPAL_ID(N'pim_engine') IS NOT NULL AND EXISTS (SELECT 1 FROM sys.database_permissions WHERE class = 1 AND major_id = OBJECT_ID(N'[$s].[usp_SupportGrant]') AND grantee_principal_id = DATABASE_PRINCIPAL_ID(N'pim_engine')) REVOKE EXECUTE ON OBJECT::[$s].[usp_SupportGrant] FROM [pim_engine];")
    [void]$b.Add((@($deny) + @($exec) + @($unexec)) -join "`n")
    if ($ConsentLevel -eq 'none') {
        # consent none: NO Support database user at all -- every open grant closed through the signed revoke (only roles a
        # grant added; the Support app's sessions ended), then the user removed (its role memberships go with it)
        [void]$b.Add("EXEC [$s].[usp_SupportRevoke] @Mode = N'all', @Source = N'consent-none';")
        [void]$b.Add(@"
-- [pimsupport] consent none: the Support app's database user is removed
DECLARE @sid VARBINARY(16) = CAST(CAST('$g' AS UNIQUEIDENTIFIER) AS VARBINARY(16)), @n SYSNAME, @q NVARCHAR(400);
SELECT @n = name FROM sys.database_principals WHERE sid = @sid AND type IN ('E', 'X', 'S', 'U');
IF @n IS NOT NULL BEGIN SET @q = N'DROP USER ' + QUOTENAME(@n) + N';'; EXEC sys.sp_executesql @q; END
"@)
    }
    return @($b.ToArray())
}

function Get-PimSupportJitUninstallBatches {
    <#
      PURE. THE UNDO of the support-session step, run by the same OWNER-LEVEL sign-in. Batches, in order:
        1 REFUSED while any grant is open (close it first: usp_SupportRevoke @Mode = all) -- an undo never leaves a role
          that a marker would have taken back
        2 the denies taken back (ALTER on the procedures, the tables, the schema), the three procedures and the two tables
          dropped
        3 the signer: its certificate user leaves db_owner and goes, the certificate goes
        4 the schema, when nothing else is in it
      The Support app's user and its read-only access STAY (4a: the standing read-only path is never removed by this).
    #>
    $s = Get-PimSupportJitSchemaName; $pfx = Get-PimSupportJitSignerPrefix
    $objs = @(Get-PimSupportJitProcedureNames) + @('GrantMarker', 'Consent')
    $b = New-Object System.Collections.Generic.List[string]
    # every statement that names an object of the schema runs as dynamic SQL: on a database without them (a second undo, a
    # never-installed one) the batch must still compile -- real SQL (test VM 2026-11-02)
    [void]$b.Add(@"
DECLARE @open INT = 0;
IF OBJECT_ID(N'[$s].[GrantMarker]') IS NOT NULL
    EXEC sys.sp_executesql N'SELECT @o = COUNT(*) FROM [$s].[GrantMarker] WHERE RevokedUtc IS NULL;', N'@o INT OUTPUT', @o = @open OUTPUT;
IF @open > 0
    THROW 51121, N'uninstall: a time-limited support access is still open -- close it first (usp_SupportRevoke @Mode = all); nothing was changed.', 1;
"@)
    $l = New-Object System.Collections.Generic.List[string]
    foreach ($o in $objs) { $l.Add("IF OBJECT_ID(N'[$s].[$o]') IS NOT NULL EXEC(N'REVOKE ALTER ON OBJECT::[$s].[$o] FROM [public];');") }
    $l.Add("IF SCHEMA_ID(N'$s') IS NOT NULL EXEC(N'REVOKE ALTER ON SCHEMA::[$s] FROM [public];');")
    foreach ($p in @(Get-PimSupportJitProcedureNames)) { $l.Add("IF OBJECT_ID(N'[$s].[$p]') IS NOT NULL EXEC(N'DROP PROCEDURE [$s].[$p];');") }
    $l.Add("IF OBJECT_ID(N'[$s].[GrantMarker]') IS NOT NULL EXEC(N'DROP TABLE [$s].[GrantMarker];');")
    $l.Add("IF OBJECT_ID(N'[$s].[Consent]') IS NOT NULL EXEC(N'DROP TABLE [$s].[Consent];');")
    [void]$b.Add($l -join "`r`n")
    [void]$b.Add(@"
DECLARE @old SYSNAME, @x NVARCHAR(MAX);
DECLARE oldc CURSOR LOCAL FAST_FORWARD FOR SELECT name FROM sys.certificates WHERE name LIKE N'$pfx%';
OPEN oldc; FETCH NEXT FROM oldc INTO @old;
WHILE @@FETCH_STATUS = 0
BEGIN
    -- the SIGNER of these procedures only (its certificate name): its user leaves db_owner and goes with it
    IF DATABASE_PRINCIPAL_ID(@old) IS NOT NULL
    BEGIN
        IF IS_ROLEMEMBER(N'db_owner', @old) = 1 BEGIN SET @x = N'ALTER ROLE [db_owner] DROP MEMBER ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @x; END
        SET @x = N'DROP USER ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @x;
    END
    SET @x = N'DROP CERTIFICATE ' + QUOTENAME(@old) + N';'; EXEC sys.sp_executesql @x;
    FETCH NEXT FROM oldc INTO @old;
END
CLOSE oldc; DEALLOCATE oldc;
"@)
    [void]$b.Add("IF SCHEMA_ID(N'$s') IS NOT NULL AND NOT EXISTS (SELECT 1 FROM sys.objects WHERE schema_id = SCHEMA_ID(N'$s')) EXEC(N'DROP SCHEMA [$s];');")
    return @($b.ToArray())
}

function Get-PimSupportJitInstallFactsSql {
    # PURE. ONE read-only JSON scalar: is the step in place? (procedures current + signed by the signer, the private key
    # removed, the signer a db_owner member, ALTER denied to public on each, the consent level, the read-only user).
    $s = Get-PimSupportJitSchemaName; $m = Get-PimSupportJitVersionMark; $pfx = Get-PimSupportJitSignerPrefix
    $per = @(Get-PimSupportJitProcedureNames | ForEach-Object {
        "(SELECT N'$_' AS name, CASE WHEN ISNULL(OBJECT_DEFINITION(OBJECT_ID(N'[$s].[$_]')), N'') LIKE N'%$m%' THEN 1 ELSE 0 END AS [current]," +
        " (SELECT TOP 1 c.name FROM sys.crypt_properties cp JOIN sys.certificates c ON c.thumbprint = cp.thumbprint WHERE cp.major_id = OBJECT_ID(N'[$s].[$_]') AND c.name LIKE N'$pfx%') AS signer," +
        " (SELECT TOP 1 CASE WHEN c.pvt_key_encryption_type = 'NA' THEN 1 ELSE 0 END FROM sys.crypt_properties cp JOIN sys.certificates c ON c.thumbprint = cp.thumbprint WHERE cp.major_id = OBJECT_ID(N'[$s].[$_]')) AS privateKeyRemoved," +
        " (SELECT TOP 1 CASE WHEN IS_ROLEMEMBER(N'db_owner', c.name) = 1 THEN 1 ELSE 0 END FROM sys.crypt_properties cp JOIN sys.certificates c ON c.thumbprint = cp.thumbprint WHERE cp.major_id = OBJECT_ID(N'[$s].[$_]')) AS signerOwner," +
        " CASE WHEN EXISTS (SELECT 1 FROM sys.database_permissions dp WHERE dp.class = 1 AND dp.major_id = OBJECT_ID(N'[$s].[$_]') AND dp.permission_name = N'ALTER' AND dp.state = 'D' AND dp.grantee_principal_id = 0) THEN 1 ELSE 0 END AS alterDenied" +
        " FOR JSON PATH, WITHOUT_ARRAY_WRAPPER)"
    })
    $r = Get-PimSupportJitReadOnlyRole
    $in = (@(Get-PimSupportJitReadSchemas) | ForEach-Object { "N'$_'" }) -join ', '
    $sidOf = "(SELECT TOP 1 CAST(SupportAppId AS VARBINARY(16)) FROM [$s].[Consent] WHERE Id = 1)"
    return ("SELECT (SELECT ISNULL((SELECT ConsentLevel FROM [$s].[Consent] WHERE Id = 1), N'none') AS consented," +
            " CASE WHEN DATABASE_PRINCIPAL_ID(N'$r') IS NULL THEN 0 ELSE 1 END AS readRole," +
            " (SELECT COUNT(*) FROM sys.database_permissions dp WHERE dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'$r') AND dp.class = 3 AND dp.permission_name = N'SELECT' AND dp.state = 'G' AND SCHEMA_NAME(dp.major_id) IN ($in)) AS readRoleSchemas," +
            " (SELECT COUNT(*) FROM sys.database_permissions dp WHERE dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'$r') AND NOT (dp.class = 3 AND dp.permission_name = N'SELECT' AND dp.state = 'G' AND SCHEMA_NAME(dp.major_id) IN ($in))) AS readRoleOther," +
            " (SELECT COUNT(*) FROM sys.schemas WHERE name IN ($in)) AS productSchemas," +
            " CASE WHEN EXISTS (SELECT 1 FROM sys.database_principals WHERE sid = $sidOf) THEN 1 ELSE 0 END AS userExists," +
            " CASE WHEN EXISTS (SELECT 1 FROM sys.database_principals p WHERE p.sid = $sidOf AND IS_ROLEMEMBER(N'$r', p.name) = 1) THEN 1 ELSE 0 END AS readOnly," +
            " CASE WHEN EXISTS (SELECT 1 FROM sys.database_principals p WHERE p.sid = $sidOf AND IS_ROLEMEMBER(N'$(Get-PimSupportJitLegacyReadOnlyRole)', p.name) = 1) THEN 1 ELSE 0 END AS legacyReader," +
            " CASE WHEN EXISTS (SELECT 1 FROM sys.database_permissions dp WHERE dp.class = 1 AND dp.major_id = OBJECT_ID(N'[$s].[usp_SupportGrant]') AND dp.grantee_principal_id = DATABASE_PRINCIPAL_ID(N'pim_engine') AND dp.state IN ('G', 'W')) THEN 1 ELSE 0 END AS engineMayOpen," +
            " (SELECT COUNT(*) FROM sys.objects o WHERE o.schema_id = SCHEMA_ID(N'$s') AND o.type IN ('U', 'V', 'P', 'PC', 'FN', 'IF', 'TF', 'TR', 'SN') AND o.name NOT IN (N'Consent', N'GrantMarker', N'usp_SupportGrant', N'usp_SupportRevoke', N'usp_SupportState')) AS foreignObjects," +
            " JSON_QUERY(N'[' + " + ($per -join " + N',' + ") + " + N']') AS procedures FOR JSON PATH, WITHOUT_ARRAY_WRAPPER) AS result")
}

# ======================================================================================================== the callers
function ConvertFrom-PimSupportJitAnswer {
    # PURE. A procedure's ONE JSON scalar -> an object. Anything else THROWS (no answer is never "nothing open").
    param([AllowNull()]$Raw)
    $t = "$Raw".Trim()
    if (-not $t.StartsWith('{')) { throw 'the database did not answer the support access procedure' }
    return ($t | ConvertFrom-Json)
}

function Get-PimSupportJitFirstLine { param($e) return (("$($e.Exception.Message)" -split "`n")[0]).Trim() }

function Test-PimSupportJitNotInstalled {
    # PURE. Is this error the procedure (or its schema) missing on this install -- the support-session step not run yet?
    param([AllowNull()][string]$Message)
    return [bool]("$Message" -match '(?i)Could not find stored procedure|Msg 2812|Invalid object name .pimsupport')
}

function Invoke-PimSupportJitGrant {
    <#
      Open (or extend) the support access through the SIGNED procedure. Never throws. -Level troubleshoot | setup (v1 read /
      owner are mapped), -Hours 1-8; -UntilUtc: an exact end (the earlier of it and -Hours wins, inside the procedure too).
      Returns { ok; level; requested; consented; grantId; untilUtc; rolesAdded; extended; preExisting; readOnly; inOwner;
      installed; problem }. The procedure decides the level (the LOWER of requested and consented); nothing here can widen it.
    #>
    param([Parameter(Mandatory)][scriptblock]$Sql, [ValidateSet('troubleshoot', 'setup', 'read', 'owner')][string]$Level = 'setup', [int]$Hours = (Get-PimSupportJitDefaultHours),
          [string]$Reason = '', [string]$Ticket = '', [string]$OpenedBy = '', [AllowNull()][object]$UntilUtc = $null)
    $Level = ConvertTo-PimSupportJitLevel $Level
    $o = [ordered]@{ ok = $false; level = ''; requested = $Level; consented = ''; grantId = ''; untilUtc = ''; rolesAdded = 0; extended = $false; preExisting = $false
                     readOnly = $false; inOwner = $false; installed = $true; problem = '' }
    try {
        if ($Hours -lt 1 -or $Hours -gt (Get-PimSupportJitMaxHours)) { $o.problem = "the support access may last 1 to $(Get-PimSupportJitMaxHours) hours -- nothing was changed"; return [pscustomobject]$o }
        $untilSql = 'NULL'
        if ($null -ne $UntilUtc -and "$UntilUtc".Trim()) {
            $uu = ConvertFrom-PimSupportJitUtc $UntilUtc
            if (-not $uu) { $o.problem = "the end '$UntilUtc' is not a UTC time -- nothing was changed"; return [pscustomobject]$o }
            $untilSql = "'" + $uu.ToString('yyyy-MM-ddTHH:mm:ss', [Globalization.CultureInfo]::InvariantCulture) + "'"
        }
        $s = Get-PimSupportJitSchemaName
        $q = "EXEC [$s].[usp_SupportGrant] @Level = N'$Level', @Hours = $([int]$Hours), @Reason = $(ConvertTo-PimSupportJitSqlText (ConvertTo-PimSupportJitText $Reason 120)), @Ticket = $(ConvertTo-PimSupportJitSqlText (ConvertTo-PimSupportJitText $Ticket 40)), @OpenedBy = $(ConvertTo-PimSupportJitSqlText (ConvertTo-PimSupportJitText $OpenedBy 120)), @UntilUtc = $untilSql;"
        $a = ConvertFrom-PimSupportJitAnswer (& $Sql $q)
        $o.level = "$($a.level)"; $o.consented = "$($a.consented)"; $o.grantId = "$($a.grantId)"
        $u = ConvertFrom-PimSupportJitUtc $a.untilUtc; $o.untilUtc = if ($u) { Format-PimSupportJitUtc -Utc $u } else { '' }
        $o.rolesAdded = [int]$a.rolesAdded; $o.extended = ([int]$a.extended -eq 1); $o.preExisting = ([int]$a.preExisting -eq 1)
        $o.readOnly = ([int]$a.readOnly -eq 1); $o.inOwner = ([int]$a.inOwner -eq 1)
        $why = @()
        if (-not $o.readOnly) { $why += "the Support app's user is not in $(Get-PimSupportJitReadOnlyRole)" }
        if ($o.level -eq 'setup' -and -not $o.inOwner) { $why += "the Support app's user is not in $(Get-PimSupportJitAdminRole)" }
        if ($o.level -eq 'setup' -and -not $o.untilUtc) { $why += 'no end is recorded for the admin access' }
        if ($why.Count) { $o.problem = "read-back: $($why -join '; ')" } else { $o.ok = $true }
    } catch {
        $o.problem = Get-PimSupportJitFirstLine $_
        if (Test-PimSupportJitNotInstalled $o.problem) { $o.installed = $false; $o.problem = "$(Get-PimSupportJitNotSetUpText) (the support-session step sets it up) -- nothing was changed" }
    }
    return [pscustomobject]$o
}

function Invoke-PimSupportJitRevoke {
    <#
      Close the support access through the SIGNED procedure: -Mode expired (THE SWEEP: every marker past its end) or all
      (support closed: every open marker). Never throws. -Source names who did it (job | heartbeat | manager | script).
      -Audit { param($Record) } gets ONE record per marker closed or failed: { action = support.access.revoke |
      support.access.close; target; source; role; grantId; expiresUtc; preExisting; roleRemoved; result ok|failed; detail }.
      LOUD (Write-Warning + problems): a marker that could not be closed, a call that failed, an audit that could not be
      written. 'Not set up' (the procedures missing on this install) is NOT loud: no grant can exist where they do not -- it is
      a plain state (Get-PimSupportJitNotSetUpText), and only a real failure once they are installed is loud.
      Returns { ok; installed; mode; found; revoked; failed; sessionsEnded; open; jitOpen; jitUntil; problems }.
    #>
    [CmdletBinding()]
    param([AllowNull()][scriptblock]$Sql, [ValidateSet('expired', 'all')][string]$Mode = 'expired', [string]$Source = 'unknown', [AllowNull()][scriptblock]$Audit = $null, [switch]$Quiet)
    $problems = New-Object System.Collections.Generic.List[string]
    $res = [ordered]@{ ok = $false; installed = $null; mode = $Mode; found = 0; revoked = @(); failed = @(); sessionsEnded = 0; open = @(); jitOpen = $null; jitUntil = ''; problems = @() }
    $loud = { param([string]$m) $problems.Add($m); Write-Warning "[support-access] $m" }
    $finish = { $res.problems = @($problems.ToArray()); $res.ok = [bool]($null -ne $res.installed -and -not @($res.failed).Count -and -not $problems.Count); return [pscustomobject]$res }
    if (-not $Sql) { & $loud "no database session in this $Source run -- the support access was not checked and an ended grant, if any, was NOT taken back"; return (& $finish) }
    $src = ConvertTo-PimSupportJitText -Text $Source -Max 20
    $a = $null
    try { $a = ConvertFrom-PimSupportJitAnswer (& $Sql "EXEC [$(Get-PimSupportJitSchemaName)].[usp_SupportRevoke] @Mode = N'$Mode', @Source = $(ConvertTo-PimSupportJitSqlText $src);") }
    catch {
        $m = Get-PimSupportJitFirstLine $_
        if (Test-PimSupportJitNotInstalled $m) { $res.installed = $false; $res.jitOpen = $false; return (& $finish) }
        & $loud "the support access could not be closed in this $Source run ($m) -- an ended grant, if any, was NOT taken back; every run tries again"
        return (& $finish)
    }
    $res.installed = $true
    $act = if ($Mode -eq 'all') { 'support.access.close' } else { 'support.access.revoke' }
    $fmt = { param($v) $d = ConvertFrom-PimSupportJitUtc $v; if ($d) { Format-PimSupportJitUtc -Utc $d } else { '' } }
    $res.found = [int]$a.found; $res.sessionsEnded = [int]$a.sessionsEnded
    $rv = @(@($a.revoked) | Where-Object { $_ } | ForEach-Object { [pscustomobject]@{ grantId = "$($_.grantId)"; role = "$($_.role)"; userName = "$($_.userName)"; expiresUtc = (& $fmt $_.expiresUtc); preExisting = ([int]$_.preExisting -eq 1); roleRemoved = ([int]$_.removed -eq 1) } })
    $fl = @(@($a.failed) | Where-Object { $_ } | ForEach-Object { [pscustomobject]@{ grantId = "$($_.grantId)"; role = "$($_.role)"; userName = "$($_.userName)"; expiresUtc = (& $fmt $_.expiresUtc); error = "$($_.error)" } })
    $op = @(@($a.open) | Where-Object { $_ } | ForEach-Object { [pscustomobject]@{ role = "$($_.role)"; expiresUtc = (& $fmt $_.expiresUtc) } })
    $res.revoked = $rv; $res.failed = $fl; $res.open = $op
    foreach ($r in $rv) {
        $rec = [pscustomobject][ordered]@{ action = $act; target = "database user [$($r.userName)]"; source = $src; role = $r.role; grantId = $r.grantId; expiresUtc = $r.expiresUtc
                                          preExisting = $r.preExisting; roleRemoved = $r.roleRemoved; sessionsEnded = $res.sessionsEnded; result = 'ok'; detail = '' }
        if ($Audit) { try { & $Audit $rec } catch { & $loud "the audit record of the revoke of $($r.role) for database user [$($r.userName)] could not be written: $(Get-PimSupportJitFirstLine $_)" } }
        if (-not $Quiet) { Write-Host "  [support-access] closed: $($r.role) of database user [$($r.userName)]$(if ($r.preExisting) { ' (held before the grant: kept)' } else { ' taken back' }); the read-only access stays" -ForegroundColor Green }
    }
    foreach ($f in $fl) {
        $rec = [pscustomobject][ordered]@{ action = $act; target = "database user [$($f.userName)]"; source = $src; role = $f.role; grantId = $f.grantId; expiresUtc = $f.expiresUtc
                                          preExisting = $null; roleRemoved = $false; sessionsEnded = $res.sessionsEnded; result = 'failed'; detail = $f.error }
        if ($Audit) { try { & $Audit $rec } catch { & $loud "the audit record of the failed revoke for database user [$($f.userName)] could not be written: $(Get-PimSupportJitFirstLine $_)" } }
        & $loud "$($f.role) of database user [$($f.userName)] (end $($f.expiresUtc)) could NOT be taken back by this $Source run ($($f.error)) -- THE ACCESS IS STILL IN PLACE; every run tries again"
    }
    # the sessions: a role taken back while the Support app's session stays open is NOT ended in that session (SQL Server
    # keeps a session's role memberships until it reconnects) -- so sessions that could not be seen or ended are LOUD
    $res.sessionsNotEnded = 0; $res.sessionsChecked = $null
    $res.endedSessions = @(@($a.endedSessions) | Where-Object { $_ } | ForEach-Object { [pscustomobject]@{ id = [int]$_.id; login = "$($_.login)"; originalLogin = "$($_.originalLogin)" } })
    if ($a.PSObject.Properties['sessionsNotEnded']) { $res.sessionsNotEnded = [int]$a.sessionsNotEnded }
    if ($a.PSObject.Properties['sessionsChecked']) { $res.sessionsChecked = ([int]$a.sessionsChecked -eq 1) }
    if (@($rv | Where-Object { $_.roleRemoved }).Count) {
        if ($res.sessionsChecked -eq $false) { & $loud "this $Source run could not see the Support app's open database sessions (no right to see other sessions) -- a session opened before the end may keep the admin right until it reconnects" }
        if ($res.sessionsNotEnded -gt 0) { & $loud "$($res.sessionsNotEnded) open database session(s) of the Support app could NOT be ended in this $Source run ($("$($a.sessionError)".Trim())) -- they may keep the admin right until they reconnect" }
    }
    $still = @(@($op | ForEach-Object { $_.expiresUtc }) | Where-Object { $_ } | Sort-Object)
    $res.jitOpen = [bool]($op.Count -gt 0)
    $res.jitUntil = if ($still.Count) { "$($still[-1])" } else { '' }
    return (& $finish)
}

function Invoke-PimSupportJitSweep {
    <# THE SWEEP: Invoke-PimSupportJitRevoke -Mode expired. Every regular runner calls this (job, heartbeat, Manager). #>
    [CmdletBinding()]
    param([AllowNull()][scriptblock]$Sql, [string]$Source = 'unknown', [AllowNull()][scriptblock]$Audit = $null, [switch]$Quiet)
    return (Invoke-PimSupportJitRevoke -Sql $Sql -Mode 'expired' -Source $Source -Audit $Audit -Quiet:$Quiet)
}

function Get-PimSupportJitState {
    <#
      The state through the SIGNED read procedure (the engine / web identities may not see other users themselves). Never
      throws. Returns { installed; read; consented; readOnly; inOwner; jitOpen; jitUntil; openMarkers; expiredOpen; halfDone;
      opened24h; closed24h; problem }. read = $false + problem: not determined (never a guess).
    #>
    param([AllowNull()][scriptblock]$Sql)
    $o = [ordered]@{ installed = $null; read = $false; consented = ''; appId = ''; userExists = $null; readOnly = $null; legacyReader = $null; inOwner = $null; jitOpen = $null; jitUntil = ''; openMarkers = 0; expiredOpen = 0
                     halfDone = 0; opened24h = 0; closed24h = 0; foreignObjects = 0; problem = '' }
    if (-not $Sql) { $o.problem = 'no database session'; return [pscustomobject]$o }
    try {
        $a = ConvertFrom-PimSupportJitAnswer (& $Sql "EXEC [$(Get-PimSupportJitSchemaName)].[usp_SupportState];")
        $o.installed = $true; $o.read = $true; $o.consented = "$($a.consented)"
        $o.readOnly = ([int]$a.readOnly -eq 1); $o.inOwner = ([int]$a.inOwner -eq 1)
        # v2 fields; a v1 procedure (not yet re-installed) does not send them -> not determined ($null), never a guess
        if ($a.PSObject.Properties['appId']) { $o.appId = "$($a.appId)".Trim().ToLowerInvariant() }
        if ($a.PSObject.Properties['userExists']) { $o.userExists = ([int]$a.userExists -eq 1) }
        if ($a.PSObject.Properties['legacyReader']) { $o.legacyReader = ([int]$a.legacyReader -eq 1) }
        if ($a.PSObject.Properties['jitOpenedUtc']) { $ou = ConvertFrom-PimSupportJitUtc $a.jitOpenedUtc; $o['jitOpenedUtc'] = if ($ou) { Format-PimSupportJitUtc -Utc $ou } else { '' } }
        $o.openMarkers = [int]$a.openMarkers; $o.expiredOpen = [int]$a.expiredOpen; $o.halfDone = [int]$a.halfDone
        $o.opened24h = [int]$a.opened24h; $o.closed24h = [int]$a.closed24h
        if ($a.PSObject.Properties['foreignObjects']) { $o.foreignObjects = [int]$a.foreignObjects }
        $o.jitOpen = ($o.openMarkers -gt 0)
        $u = ConvertFrom-PimSupportJitUtc $a.jitUntil; $o.jitUntil = if ($u -and $o.jitOpen) { Format-PimSupportJitUtc -Utc $u } else { '' }
    } catch {
        $m = Get-PimSupportJitFirstLine $_
        if (Test-PimSupportJitNotInstalled $m) { $o.installed = $false; $o.jitOpen = $false; $o.problem = (Get-PimSupportJitNotSetUpText) } else { $o.problem = $m }
    }
    return [pscustomobject]$o
}

function Get-PimSupportJitStateSummary {
    # PURE. One line for a run record / the uplink detail: what was opened, closed, swept, and what needs a look.
    param([AllowNull()]$Sweep, [AllowNull()]$State)
    $p = New-Object System.Collections.Generic.List[string]
    if (($Sweep -and $Sweep.installed -eq $false) -or ($State -and $State.installed -eq $false)) { return "support access: $(Get-PimSupportJitNotSetUpText) (standing access as before)" }
    if ($Sweep) { $p.Add("swept $(@($Sweep.revoked).Count)$(if (@($Sweep.failed).Count) { ", FAILED $(@($Sweep.failed).Count)" })") }
    if ($State -and $State.read) {
        $p.Add("opened $($State.opened24h) / closed $($State.closed24h) in 24 h")
        $p.Add($(if ($State.jitOpen) { "open until $($State.jitUntil)" } else { 'none open' }))
        if ($State.halfDone) { $p.Add("$($State.halfDone) half-done") }
        if ($State.foreignObjects) { $p.Add("$($State.foreignObjects) UNEXPECTED object(s) in the support schema") }
        if ($State.consented -and $State.consented -ne 'none' -and -not $State.readOnly) { $p.Add('the read-only access is MISSING') }
    }
    return ('support access: ' + ($p -join '; '))
}

function Test-PimSupportJitNeedsLook {
    # PURE. Does the sweep / state need a person (an uplink WARNING)? A failed revoke, an error, a half-done grant, an open
    # grant past its end, or a consenting install without its read-only access (4a).
    param([AllowNull()]$Sweep, [AllowNull()]$State)
    if ($Sweep -and (@($Sweep.failed).Count -or @($Sweep.problems).Count)) { return $true }
    if ($State -and $State.read -and ($State.halfDone -gt 0 -or $State.expiredOpen -gt 0 -or $State.foreignObjects -gt 0)) { return $true }
    if ($State -and $State.read -and $State.consented -and $State.consented -ne 'none' -and -not $State.readOnly) { return $true }
    return $false
}

function Invoke-PimSupportJitInstall {
    <#
      THE SUPPORT-SESSION STEP: run Get-PimSupportJitInstallBatches through -Sql (an OWNER-LEVEL sign-in) and READ IT BACK
      (Get-PimSupportJitInstallFactsSql). Never throws. Returns { ok; consented; procedures; problems }. ok only when every
      procedure is current, signed by the signer, its private key removed, the signer a db_owner member and ALTER denied.
    #>
    param([Parameter(Mandatory)][scriptblock]$Sql, [Parameter(Mandatory)][string]$SupportAppId, [Parameter(Mandatory)][ValidateSet('none', 'troubleshoot', 'setup', 'read', 'owner')][string]$ConsentLevel,
          [string]$UserName = 'invardia-support', [string]$SetBy = '')
    $ConsentLevel = ConvertTo-PimSupportJitLevel $ConsentLevel     # v1 words mapped (read -> troubleshoot, owner -> setup), never widened
    $problems = New-Object System.Collections.Generic.List[string]
    $o = [ordered]@{ ok = $false; consented = ''; procedures = @(); readOnly = $false; userExists = $false; problems = @() }
    try {
        $i = 0
        foreach ($bt in @(Get-PimSupportJitInstallBatches -SupportAppId $SupportAppId -ConsentLevel $ConsentLevel -UserName $UserName -SetBy $SetBy)) {
            $i++
            try { [void](& $Sql $bt) } catch { $problems.Add("step $i of the installation was refused: $(Get-PimSupportJitFirstLine $_)"); break }
        }
        $f = ConvertFrom-PimSupportJitAnswer (& $Sql (Get-PimSupportJitInstallFactsSql))
        $o.consented = "$($f.consented)"
        $o.procedures = @(@($f.procedures) | Where-Object { $_ })
        foreach ($n in @(Get-PimSupportJitProcedureNames)) {
            $p = @($o.procedures | Where-Object { "$($_.name)" -eq $n }) | Select-Object -First 1
            if (-not $p) { $problems.Add("$n is not there"); continue }
            if ([int]$p.current -ne 1) { $problems.Add("$n is not this version") }
            if (-not "$($p.signer)".StartsWith((Get-PimSupportJitSignerPrefix))) { $problems.Add("$n is not signed") }
            if ([int]$p.privateKeyRemoved -ne 1) { $problems.Add("the private key of the signer of $n is still there") }
            if ([int]$p.signerOwner -ne 1) { $problems.Add("the signer of $n is not a db_owner member") }
            if ([int]$p.alterDenied -ne 1) { $problems.Add("ALTER on $n is not denied") }
        }
        if ($o.consented -ne $ConsentLevel) { $problems.Add("the consent reads back as '$($o.consented)', not '$ConsentLevel'") }
        # v2 (OPEN-01): the read role exactly as agreed, and the Support user as the consent says
        if ($f.PSObject.Properties['readRole']) {
            $ro = Get-PimSupportJitReadOnlyRole
            $o.readOnly = ([int]$f.readOnly -eq 1); $o.userExists = ([int]$f.userExists -eq 1)
            if ([int]$f.readRole -ne 1) { $problems.Add("the read role $ro is not there") }
            elseif ([int]$f.readRoleSchemas -ne [int]$f.productSchemas) { $problems.Add("the read role $ro does not hold SELECT on every product schema ($([int]$f.readRoleSchemas) of $([int]$f.productSchemas))") }
            if ([int]$f.readRoleOther -gt 0) { $problems.Add("the read role $ro holds $([int]$f.readRoleOther) right(s) beyond SELECT on the product schemas") }
            if ([int]$f.engineMayOpen -eq 1) { $problems.Add('the engine may still open the support access (EXECUTE on usp_SupportGrant)') }
            if ($ConsentLevel -eq 'none' -and $o.userExists) { $problems.Add('consent none, but the Support app''s database user is still there') }
            if ($ConsentLevel -ne 'none' -and -not $o.readOnly) { $problems.Add("the Support app's database user is not in $ro") }
            if ($ConsentLevel -ne 'none' -and [int]$f.legacyReader -eq 1) { $problems.Add("the Support app's database user is still in $(Get-PimSupportJitLegacyReadOnlyRole) (v1)") }
        }
        if ($f.PSObject.Properties['foreignObjects'] -and [int]$f.foreignObjects -gt 0) { $problems.Add("$([int]$f.foreignObjects) object(s) in the support schema that this step did not make -- an owner must look at and remove them") }
    } catch { $problems.Add((Get-PimSupportJitFirstLine $_)) }
    $o.problems = @($problems.ToArray()); $o.ok = ($problems.Count -eq 0)
    return [pscustomobject]$o
}

# ===== END inlined helper: ..\..\engine\_shared\PIM-SupportJit.ps1 =====

function Get-PimSupportSqlJobDefaultName { return 'caj-pim-supportsql' }
function Get-PimSupportSqlJobTemplateName { return 'ca-pim-dbinit' }
function Get-PimSupportSqlJobAcaApi { return '2024-03-01' }
function Get-PimSupportSqlJobTagName { return 'pim-one-time-job' }
function Get-PimSupportSqlJobTagValue { return 'support-sql-access' }
function Get-PimSupportSqlJobScriptName { return 'Invoke-PimSupportSqlAccessJob' }
function Get-PimSupportSqlJobDefaultAppRoot { return '/app/PIM4EntraPS' }
function Get-PimSupportSqlJobIdentitySetting { return 'PIM_DBINIT_MI_CLIENT_ID' }
function Get-PimSupportSqlJobUntilTagName { return 'pim-support-until' }

function Get-PimSupportSqlJobFunctionNames {
    # PURE. The functions the job carries, in load order: those of _PimSupportSqlAccess.ps1 (the standing grant) and those
    # of engine/_shared/PIM-SupportJit.ps1 (the time-limited grant, the revoke and the sweep). Nothing else runs inside.
    return @('Get-PimSupportSqlUserDefaultName', 'Get-PimSupportSqlRoleName', 'Get-PimSupportSqlLegacyRoleNames', 'ConvertTo-PimSupportSqlSid', 'Test-PimSupportSqlNames',
             'Get-PimSupportSqlUserSql', 'Get-PimSupportSqlUserReadSql', 'ConvertFrom-PimSupportSqlUserRead', 'Invoke-PimSupportSqlUser', 'Invoke-PimSupportSqlReadOnlyUser',
             'Get-PimSupportJitSchemaName', 'Get-PimSupportJitVersionMark', 'Get-PimSupportJitSignerPrefix', 'Get-PimSupportJitProcedureNames',
             'Get-PimSupportJitAdminRole', 'Get-PimSupportJitReadOnlyRole', 'Get-PimSupportJitReadSchemas', 'Get-PimSupportJitLegacyReadOnlyRole', 'Get-PimSupportJitDefaultHours', 'Get-PimSupportJitMaxHours',
             'Get-PimSupportJitNotSetUpText', 'Get-PimSupportJitLevels', 'ConvertTo-PimSupportJitLevel', 'Get-PimSupportJitLowerLevel', 'Test-PimSupportJitUserName', 'ConvertTo-PimSupportJitText',
             'Format-PimSupportJitUtc', 'ConvertFrom-PimSupportJitUtc', 'ConvertTo-PimSupportJitSqlText', 'Get-PimSupportJitTableSql', 'Get-PimSupportJitReadRoleSql',
             'Get-PimSupportJitProcedureText', 'Get-PimSupportJitInstallBatches', 'Get-PimSupportJitInstallFactsSql', 'ConvertFrom-PimSupportJitAnswer',
             'Get-PimSupportJitFirstLine', 'Test-PimSupportJitNotInstalled', 'Invoke-PimSupportJitGrant', 'Invoke-PimSupportJitRevoke',
             'Invoke-PimSupportJitSweep', 'Get-PimSupportJitState', 'Get-PimSupportJitStateSummary', 'Test-PimSupportJitNeedsLook', 'Invoke-PimSupportJitInstall')
}

function ConvertTo-PimSupportSqlJobMap {
    # PURE. A JSON object or a dictionary -> an ordered name -> value table (empty for nothing).
    param([AllowNull()]$Object)
    $o = [ordered]@{}
    if ($null -eq $Object) { return $o }
    if ($Object -is [System.Collections.IDictionary]) { foreach ($k in @($Object.Keys)) { $o["$k"] = $Object[$k] }; return $o }
    foreach ($p in @($Object.PSObject.Properties)) { $o["$($p.Name)"] = $p.Value }
    return $o
}

function Get-PimSupportSqlJobScript {
    <#
      PURE (reads only the functions loaded in this process). The PowerShell the one-time job runs: the token client and
      the SQL client of the image, the grant functions of _PimSupportSqlAccess.ps1 word for word, one call of
      Invoke-PimSupportSqlUser as the identity named in PIM_SUPPORTSQL_MI_CLIENT_ID, and ONE result line
      "[supportsql] RESULT {json}". Exit 0 only when the user and its role were READ BACK.
      state (standing): created | in-place | failed.
      PIM_SUPPORTSQL_MODE (framework SECAUDIT-1a 4b / 4c; engine/_shared/PIM-SupportJit.ps1):
        standing (default)  OPEN-01: the STANDING READ-ONLY user (Invoke-PimSupportSqlReadOnlyUser; consent
                            PIM_SUPPORTSQL_CONSENT_LEVEL troubleshoot | setup, '' = as recorded, else troubleshoot) --
                            never db_owner; an earlier db_owner is reported (legacyOwner), never "in place"
        install             THE SUPPORT-SESSION STEP: consent (PIM_SUPPORTSQL_CONSENT_LEVEL), the read-only user, the
                            signed procedures; read back. Needs an owner-level identity (the database setup job's).
        grant               4b: usp_SupportGrant (PIM_SUPPORTSQL_JIT_LEVEL / _HOURS / _REASON / _TICKET / _OPENED_BY); for an
                            owner grant the job stays, follows the end (a re-open moves it later) and at the end SWEEPS
                            ("[supportsql] REVOKE {json}") -- never before the end. Exit 0 only when that sweep is clean.
        close               support closed: every open marker closed now (only roles the grant added), sessions ended
        consent             OPEN-01: ONE action the UPDATER decided from Invardia's consent channel
                            (PIM_SUPPORTSQL_CONSENT_ACTION ensure-read-user | remove-user | open-admin | close-admin,
                            PIM_SUPPORTSQL_CONSENT_LEVEL troubleshoot | setup | none, PIM_SUPPORTSQL_JIT_UNTIL for open-admin).
                            The support-session step with Invardia's consent first (idempotent: objects current + signed,
                            the read role, the consent row, the read user -- or for none every grant closed and the user
                            removed), then the open / close, then the state READ BACK. Exit 0 only when it reads back as asked.
      Every mode but install first SWEEPS ("[supportsql] SWEEP {json}"); every open / close / revoke is audited
      ("[supportsql] AUDIT {json}" + a row in the audit table when the image has the writer).
    #>
    param([string]$AppRoot = (Get-PimSupportSqlJobDefaultAppRoot))
    $root = "$AppRoot".Trim().TrimEnd('/')
    if ($root -notmatch '^[A-Za-z0-9_./:~ -]+$') { throw "Get-PimSupportSqlJobScript: '$AppRoot' is not a safe folder path." }
    $l = New-Object System.Collections.Generic.List[string]
    $l.Add('$ErrorActionPreference = ''Stop''')
    $l.Add('$rc = 1')
    $l.Add('function Write-SupportSqlLine { param([string]$Message) Write-Host (''[supportsql] '' + $Message) }')
    foreach ($n in @(Get-PimSupportSqlJobFunctionNames)) {
        $c = Get-Command -Name $n -CommandType Function -ErrorAction SilentlyContinue
        if (-not $c) { throw "Get-PimSupportSqlJobScript: the function $n is not loaded (_PimSupportSqlAccess.ps1)." }
        $l.Add("function $n {")
        $l.Add("$($c.Definition)")
        $l.Add('}')
    }
    $main = @'
try {
    Write-SupportSqlLine 'start: the database user of the Invardia Support app (PIM Manager, one-time job)'
    . '__APPROOT__/engine/_shared/PIM-Rest.ps1'
    . '__APPROOT__/engine/_shared/PIM-SqlStore.ps1'
    $server = "$($env:PIM_SqlServer)".Trim()
    $database = "$($env:PIM_SqlDatabase)".Trim()
    if (-not $database) { $database = 'PimPlatform' }
    $appId = "$($env:PIM_SUPPORTSQL_APP_ID)".Trim()
    $userName = "$($env:PIM_SUPPORTSQL_DB_USER)".Trim()
    if (-not $userName) { $userName = Get-PimSupportSqlUserDefaultName }
    $miClientId = "$($env:PIM_SUPPORTSQL_MI_CLIENT_ID)".Trim()
    if (-not $server -or -not $appId -or -not $miClientId) { throw 'PIM_SqlServer, PIM_SUPPORTSQL_APP_ID and PIM_SUPPORTSQL_MI_CLIENT_ID must all be set -- nothing was changed' }
    $global:PIM_ManagedIdentityClientId = $miClientId
    $supportSql = @{ calls = 0; conn = "Server=tcp:$server,1433;Database=$database;Encrypt=True;TrustServerCertificate=False;Connection Timeout=60" }
    Write-SupportSqlLine "database $server / $database, signing in as the managed identity $miClientId"
    $sql = {
        param([string]$Query)
        $supportSql.calls++
        $c = New-PimSqlConnection -ConnectionString $supportSql.conn
        $c.Open()
        try { $cmd = $c.CreateCommand(); $cmd.CommandText = $Query; $cmd.CommandTimeout = 120; return $cmd.ExecuteScalar() } finally { $c.Close() }
    }
    # every grant and every revoke is audited: a log line always, and a row in the audit table when the image has the writer
    $jobAudit = {
        param($Record)
        Write-SupportSqlLine ('AUDIT ' + ($Record | ConvertTo-Json -Compress))
        if (Get-Command Write-PimSqlAuditEvent -ErrorAction SilentlyContinue) {
            Write-PimSqlAuditEvent -ConnectionString $supportSql.conn -Actor 'job:support-access' -ActorSource 'job' -Action "$($Record.action)" -Target "$($Record.target)" -After $Record -Result "$($Record.result)"
        }
    }
    $sweepLine = {
        param($S)
        [ordered]@{ ok = [bool]$S.ok; installed = $S.installed; found = [int]$S.found; revoked = @($S.revoked).Count; failed = @($S.failed).Count
                    sessionsEnded = [int]$S.sessionsEnded; jitOpen = $S.jitOpen; jitUntil = "$($S.jitUntil)"; problems = @($S.problems) }
    }
    $mode = "$($env:PIM_SUPPORTSQL_MODE)".Trim().ToLowerInvariant()
    if (-not $mode) { $mode = 'standing' }
    if ($mode -notin @('standing', 'install', 'grant', 'close', 'consent')) { throw "PIM_SUPPORTSQL_MODE '$mode' is not standing, install, grant, close or consent -- nothing was changed" }
    $sweepBad = $false; $sw0Line = $null
    if ($mode -ne 'install') {
        # ---- the sweep FIRST (framework SECAUDIT-1a 4c): every marker past its end is taken back before anything is given
        $sw0 = Invoke-PimSupportJitSweep -Sql $sql -Source 'job' -Audit $jobAudit -Quiet
        $sw0Line = & $sweepLine $sw0
        Write-SupportSqlLine ('SWEEP ' + ($sw0Line | ConvertTo-Json -Compress))
        if ($sw0.installed -eq $false) { Write-SupportSqlLine (Get-PimSupportJitNotSetUpText) }
        $sweepBad = [bool](-not $sw0.ok)
        $supportSql.calls = 0
    }
    if ($mode -eq 'install') {
        # ---- THE SUPPORT-SESSION STEP (4c): consent, the standing read-only user, the signed procedures. Owner-level identity.
        $consent = "$($env:PIM_SUPPORTSQL_CONSENT_LEVEL)".Trim().ToLowerInvariant()
        $i = Invoke-PimSupportJitInstall -Sql $sql -SupportAppId $appId -ConsentLevel $consent -UserName $userName -SetBy "$($env:PIM_SUPPORTSQL_JIT_OPENED_BY)"
        try { & $jobAudit ([pscustomobject][ordered]@{ action = 'support.access.install'; target = 'the support access procedures'; source = 'job'; consented = "$($i.consented)"; result = $(if ($i.ok) { 'ok' } else { 'failed' }); detail = (@($i.problems) -join '; ') }) }
        catch { Write-SupportSqlLine ('WARNING the audit record of the installation could not be written: ' + ((("$($_.Exception.Message)" -split "`n")[0]).Trim())) }
        $result = [ordered]@{ ok = [bool]$i.ok; state = $(if ($i.ok) { 'installed' } else { 'failed' }); mode = 'install'; consented = "$($i.consented)"; userName = $userName
                              procedures = @($i.procedures); problem = (@($i.problems) -join '; ') }
        Write-SupportSqlLine ('RESULT ' + ($result | ConvertTo-Json -Compress -Depth 4))
        if ($i.ok) { $rc = 0 }
    } elseif ($mode -eq 'consent') {
        # ---- OPEN-01: ONE action the UPDATER decided from Invardia's consent channel (framework "SUPPORT ACCESS" point 2)
        $action = "$($env:PIM_SUPPORTSQL_CONSENT_ACTION)".Trim().ToLowerInvariant()
        $consent = ConvertTo-PimSupportJitLevel "$($env:PIM_SUPPORTSQL_CONSENT_LEVEL)"
        if ($action -notin @('ensure-read-user', 'remove-user', 'open-admin', 'close-admin')) { throw "PIM_SUPPORTSQL_CONSENT_ACTION '$action' is not ensure-read-user, remove-user, open-admin or close-admin -- nothing was changed" }
        if (-not $consent) { throw "PIM_SUPPORTSQL_CONSENT_LEVEL '$($env:PIM_SUPPORTSQL_CONSENT_LEVEL)' is not troubleshoot, setup or none -- nothing was changed" }
        if ($action -eq 'remove-user') { $consent = 'none' }
        if ($action -eq 'open-admin' -and $consent -ne 'setup') { throw "open-admin needs the consent level setup (Invardia says '$consent') -- nothing was given" }
        $cp = New-Object System.Collections.Generic.List[string]
        # 1. the support-session step with Invardia's consent (idempotent; for none: every grant closed, the user removed)
        $i = Invoke-PimSupportJitInstall -Sql $sql -SupportAppId $appId -ConsentLevel $consent -UserName $userName -SetBy "$($env:PIM_SUPPORTSQL_JIT_OPENED_BY)"
        foreach ($ip in @($i.problems)) { $cp.Add("$ip") }
        $g = $null; $cl = $null
        # 2. the open (setup inside an open support session) or the close
        if ($action -eq 'open-admin' -and $i.ok) {
            $g = Invoke-PimSupportJitGrant -Sql $sql -Level 'setup' -Hours (Get-PimSupportJitMaxHours) -UntilUtc "$($env:PIM_SUPPORTSQL_JIT_UNTIL)" -Reason "$($env:PIM_SUPPORTSQL_JIT_REASON)" -Ticket "$($env:PIM_SUPPORTSQL_JIT_TICKET)" -OpenedBy "$($env:PIM_SUPPORTSQL_JIT_OPENED_BY)"
            if (-not $g.ok) { $cp.Add("the open: $($g.problem)") }
            try { & $jobAudit ([pscustomobject][ordered]@{ action = 'support.access.open'; target = 'the Support app''s database user'; source = 'job:consent'; level = "$($g.level)"; requested = 'setup'; consented = "$($g.consented)"
                                                             grantId = "$($g.grantId)"; untilUtc = "$($g.untilUtc)"; result = $(if ($g.ok) { 'ok' } else { 'failed' }); detail = "$($g.problem)" }) }
            catch { Write-SupportSqlLine ('WARNING the audit record of the open could not be written: ' + ((("$($_.Exception.Message)" -split "`n")[0]).Trim())) }
        } elseif ($action -eq 'close-admin') {
            $cl = Invoke-PimSupportJitRevoke -Sql $sql -Mode 'all' -Source 'job' -Audit $jobAudit -Quiet
            foreach ($cq in @($cl.problems)) { $cp.Add("the close: $cq") }
        }
        try { & $jobAudit ([pscustomobject][ordered]@{ action = 'support.consent.apply'; target = 'the Support app''s database access'; source = 'job:consent'; consentAction = $action; consented = $consent
                                                         result = $(if ($cp.Count) { 'failed' } else { 'ok' }); detail = (@($cp.ToArray()) -join '; ') }) }
        catch { Write-SupportSqlLine ('WARNING the audit record of the consent could not be written: ' + ((("$($_.Exception.Message)" -split "`n")[0]).Trim())) }
        # 3. READ BACK: the state as the action asked for it
        $st = Get-PimSupportJitState -Sql $sql
        if (-not $st.read) { $cp.Add("the state could not be read back ($($st.problem))") }
        else {
            switch ($action) {
                'ensure-read-user' { if (-not $st.readOnly) { $cp.Add('read-back: the Support app''s user is not in the read role') } }
                'remove-user'      { if ($st.userExists -ne $false) { $cp.Add('read-back: the Support app''s database user is still there') } }
                'open-admin'       { if (-not ($st.inOwner -and $st.jitOpen)) { $cp.Add('read-back: no open admin access') } }
                'close-admin'      { if ($st.jitOpen) { $cp.Add('read-back: an admin access is still open') } }
            }
        }
        if ($sweepBad) { $cp.Add("the sweep before the action: $(@($sw0.problems) -join '; ')") }
        $result = [ordered]@{ ok = [bool](-not $cp.Count); state = $action; mode = 'consent'; action = $action; consented = "$($st.consented)"; userExists = $st.userExists; readOnly = $st.readOnly
                              inOwner = $st.inOwner; jitOpen = $st.jitOpen; jitUntil = "$($st.jitUntil)"; userName = $userName; problem = (@($cp.ToArray()) -join '; '); sweep = $sw0Line }
        Write-SupportSqlLine ('RESULT ' + ($result | ConvertTo-Json -Compress -Depth 4))
        if ($result.ok) { $rc = 0 }
    } elseif ($mode -eq 'close') {
        # ---- support closed: every open marker is closed now (only roles the grant added), then the sessions end
        $cl = Invoke-PimSupportJitRevoke -Sql $sql -Mode 'all' -Source 'job' -Audit $jobAudit -Quiet
        $result = [ordered]@{ ok = [bool]($cl.ok -and -not $sweepBad); state = $(if ($cl.installed -eq $false) { 'not-installed' } elseif ($cl.ok) { 'closed' } else { 'failed' }); mode = 'close'
                              closed = @($cl.revoked).Count; failed = @($cl.failed).Count; sessionsEnded = [int]$cl.sessionsEnded; problem = (@(@($sw0.problems) + @($cl.problems)) -join '; '); sweep = $sw0Line }
        Write-SupportSqlLine ('RESULT ' + ($result | ConvertTo-Json -Compress -Depth 4))
        if ($result.ok) { $rc = 0 }
    } elseif ($mode -eq 'grant') {
        # ---- 4b: the grant through the SIGNED procedure (the level = the LOWER of requested and consented), read back
        $hours = 0; [void][int]::TryParse("$($env:PIM_SUPPORTSQL_JIT_HOURS)".Trim(), [ref]$hours)
        $level = "$($env:PIM_SUPPORTSQL_JIT_LEVEL)".Trim().ToLowerInvariant(); if (-not $level) { $level = 'setup' }
        $level = ConvertTo-PimSupportJitLevel $level     # v1 read / owner -> troubleshoot / setup (never widened)
        if ($level -notin @('troubleshoot', 'setup')) { throw "PIM_SUPPORTSQL_JIT_LEVEL '$($env:PIM_SUPPORTSQL_JIT_LEVEL)' is not troubleshoot or setup -- nothing was given" }
        $g = Invoke-PimSupportJitGrant -Sql $sql -Level $level -Hours $hours -Reason "$($env:PIM_SUPPORTSQL_JIT_REASON)" -Ticket "$($env:PIM_SUPPORTSQL_JIT_TICKET)" -OpenedBy "$($env:PIM_SUPPORTSQL_JIT_OPENED_BY)"
        try { & $jobAudit ([pscustomobject][ordered]@{ action = 'support.access.open'; target = 'the Support app''s database user'; source = 'job'; level = "$($g.level)"; requested = "$($g.requested)"; consented = "$($g.consented)"
                                                         grantId = "$($g.grantId)"; untilUtc = "$($g.untilUtc)"; result = $(if ($g.ok) { 'ok' } else { 'failed' }); detail = "$($g.problem)" }) }
        catch { Write-SupportSqlLine ('WARNING the audit record of the grant could not be written: ' + ((("$($_.Exception.Message)" -split "`n")[0]).Trim())) }
        $problem = "$($g.problem)"; if (-not $problem -and $sweepBad) { $problem = "the sweep before the grant: $(@($sw0.problems) -join '; ')" }
        $result = [ordered]@{ ok = [bool]($g.ok -and -not $sweepBad); state = $(if (-not $g.ok) { 'failed' } elseif ($g.extended) { 'extended' } elseif ($g.level -eq 'setup' -and $g.preExisting) { 'pre-existing' } elseif ($g.level -eq 'setup') { 'granted' } else { 'read-only' })
                              mode = 'grant'; level = "$($g.level)"; requested = "$($g.requested)"; consented = "$($g.consented)"; grantId = "$($g.grantId)"; untilUtc = "$($g.untilUtc)"
                              role = (Get-PimSupportJitAdminRole); inRole = [bool]$g.inOwner; readOnly = [bool]$g.readOnly; installed = [bool]$g.installed; problem = $problem; sweep = $sw0Line }
        Write-SupportSqlLine ('RESULT ' + ($result | ConvertTo-Json -Compress -Depth 4))
        if ($g.ok -and $g.level -eq 'setup' -and $g.untilUtc) {
            # ---- hold until the end, then SWEEP on this job's OWN schedule: no answer from Invardia, no person and no other
            # job is needed for the access to end. Never before the end; a later end (a re-open) is followed.
            $end = ConvertFrom-PimSupportJitUtc "$($g.untilUtc)"
            Write-SupportSqlLine "WAIT the admin access ends at $(Format-PimSupportJitUtc -Utc $end); this job takes it back then"
            while ($true) {
                $nowW = [datetime]::UtcNow
                $st = Get-PimSupportJitState -Sql $sql
                if ($st.read) {
                    if (-not $st.jitOpen) { Write-SupportSqlLine 'WAIT the admin access was already closed'; break }
                    $u2 = ConvertFrom-PimSupportJitUtc "$($st.jitUntil)"
                    if ($u2 -and $u2 -gt $end) { $end = $u2; Write-SupportSqlLine "WAIT the end was moved to $(Format-PimSupportJitUtc -Utc $end) (the support access was opened again)" }
                } else { Write-SupportSqlLine "WAIT the support access could not be read ($($st.problem)) -- read again" }
                # one second past the end: the stored end has whole seconds, the clock does not -- the sweep must find it due
                if ($nowW -ge $end.AddSeconds(1)) { break }
                Start-Sleep -Seconds ([int][Math]::Max(1, [Math]::Min(300, [Math]::Ceiling(($end.AddSeconds(1) - $nowW).TotalSeconds))))
            }
            $sw1 = Invoke-PimSupportJitSweep -Sql $sql -Source 'job' -Audit $jobAudit -Quiet
            $sw1Line = & $sweepLine $sw1
            Write-SupportSqlLine ('REVOKE ' + ($sw1Line | ConvertTo-Json -Compress))
            if ($sw1.ok) { $rc = 0 }
        } elseif ($result.ok) { $rc = 0 }
    } else {
        # ---- OPEN-01: the STANDING READ-ONLY user (the support access step) -- never db_owner, never the SQL admin group.
        # A db_owner an earlier version gave is REPORTED (legacyOwner), never counted as "in place" and never removed here.
        $consent = "$($env:PIM_SUPPORTSQL_CONSENT_LEVEL)".Trim().ToLowerInvariant()
        if ($consent -and $consent -notin @('troubleshoot', 'setup')) { throw "PIM_SUPPORTSQL_CONSENT_LEVEL '$consent' is not troubleshoot or setup -- nothing was changed" }
        $u = Invoke-PimSupportSqlReadOnlyUser -Sql $sql -AppId $appId -DbUserName $userName -ConsentLevel $consent -SetBy "$($env:PIM_SUPPORTSQL_JIT_OPENED_BY)"
        $state = 'failed'
        if ($u.ok) { if ($u.created) { $state = 'created' } else { $state = 'in-place' } }
        $problem = "$($u.problem)"; if (-not $problem -and $sweepBad) { $problem = "the sweep before the grant: $(@($sw0.problems) -join '; ')" }
        $result = [ordered]@{ ok = [bool]($u.ok -and -not $sweepBad); state = $state; userName = "$($u.userName)"; role = "$($u.role)"; inRole = [bool]$u.inRole
                              consented = "$($u.consented)"; legacy = @($u.legacy); legacyOwner = [bool]$u.legacyOwner; sessionOpen = [bool]$u.sessionOpen
                              sid = (ConvertTo-PimSupportSqlSid -AppId $appId); statements = [int]$supportSql.calls; problem = $problem; sweep = $sw0Line }
        Write-SupportSqlLine ('RESULT ' + ($result | ConvertTo-Json -Compress -Depth 4))
        if ($result.ok) { $rc = 0 }
    }
} catch {
    $m = (("$($_.Exception.Message)" -split "`n")[0]).Trim()
    $failed = [ordered]@{ ok = $false; state = 'failed'; userName = ''; role = ''; inRole = $false; sid = ''; statements = 0; problem = $m }
    Write-SupportSqlLine ('RESULT ' + ($failed | ConvertTo-Json -Compress))
}
exit $rc
'@
    $l.Add($main.Replace('__APPROOT__', $root))
    return ($l -join "`n")
}

function ConvertTo-PimSupportSqlJobCommand {
    <#
      PURE. The job's -EncodedCommand: a SMALL bootstrap that un-gzips the script and runs it. The script itself (the
      standing grant, the signed-procedure install and the time-limited functions, word for word) is larger than one
      container argument may be once it is UTF-16 + base64 (Linux: 131072 bytes per argument); gzipped it is a fraction.
      The script still ends with "exit $rc", which ends the process with that code.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $raw = [Text.Encoding]::UTF8.GetBytes($Script)
    $ms = New-Object System.IO.MemoryStream
    $gz = New-Object System.IO.Compression.GZipStream($ms, [System.IO.Compression.CompressionMode]::Compress)
    $gz.Write($raw, 0, $raw.Length); $gz.Close()
    $packed = [Convert]::ToBase64String($ms.ToArray())
    $boot = "`$b = [Convert]::FromBase64String('$packed'); `$m = New-Object System.IO.MemoryStream(,`$b); `$z = New-Object System.IO.Compression.GZipStream(`$m, [System.IO.Compression.CompressionMode]::Decompress); `$r = New-Object System.IO.StreamReader(`$z, [Text.Encoding]::UTF8); `$s = `$r.ReadToEnd(); `$r.Close(); . ([scriptblock]::Create(`$s))"
    return [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($boot))
}

function ConvertFrom-PimSupportSqlJobCommand {
    # PURE. The script inside a job's -EncodedCommand (the bootstrap of ConvertTo-PimSupportSqlJobCommand), or '' when it is not one.
    param([AllowNull()][string]$Encoded)
    try {
        $boot = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String("$Encoded"))
        if ($boot -notmatch "FromBase64String\('([A-Za-z0-9+/=]+)'\)") { return '' }
        $ms = New-Object System.IO.MemoryStream(, [Convert]::FromBase64String($Matches[1]))
        $gz = New-Object System.IO.Compression.GZipStream($ms, [System.IO.Compression.CompressionMode]::Decompress)
        $sr = New-Object System.IO.StreamReader($gz, [Text.Encoding]::UTF8)
        $s = $sr.ReadToEnd(); $sr.Close()
        return $s
    } catch { return '' }
}
function ConvertFrom-PimSupportSqlJobLog {
    # PURE. The console lines of the execution -> @{ lines (no blanks, no colour codes); result (the LAST RESULT line as an object, or $null) }.
    param([AllowNull()][string[]]$Lines)
    $out = New-Object System.Collections.Generic.List[string]
    $res = $null
    foreach ($x in @($Lines)) {
        $t = ("$x" -replace '\x1b\[[0-9;]*m', '').TrimEnd()
        if (-not $t.Trim()) { continue }
        $out.Add($t)
        if ($t -match '^\s*\[supportsql\] RESULT (\{.*\})\s*$') { try { $res = $Matches[1] | ConvertFrom-Json } catch { $res = $null } }
    }
    # PowerShell 7's ConvertFrom-Json turns an ISO date string into a [datetime], which then prints in the LOCAL format
    # ("11/01/2026 18:00:00") -- the end time must stay the exact UTC text the job wrote (2026-11-02, release 3.0.17 gate).
    if ($res) {
        foreach ($p in @($res.PSObject.Properties)) {
            if ($p.Value -is [datetime]) { $p.Value = $p.Value.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) }
        }
    }
    return @{ lines = @($out.ToArray()); result = $res }
}

function Get-PimSupportSqlJobLogQuery {
    # PURE. The Log Analytics query for the console lines of ONE execution, oldest first.
    param([Parameter(Mandatory)][string]$Execution, [int]$Take = 200)
    if ("$Execution" -notmatch '^[A-Za-z0-9][A-Za-z0-9-]{0,80}$') { throw "Get-PimSupportSqlJobLogQuery: '$Execution' is not an execution name." }
    return "ContainerAppConsoleLogs_CL | where ContainerGroupName_s startswith '$Execution' | sort by TimeGenerated asc | take $([Math]::Max(1, $Take)) | project TimeGenerated, Log_s"
}

function Get-PimSupportSqlJobOptions {
    # PURE. What a person can do when the installation has no identity this script may use. Nothing here widens a right.
    param([string]$TemplateJobName = (Get-PimSupportSqlJobTemplateName))
    return @(
        "(a) run Grant-PimSupportSqlAccess.ps1 from a machine inside the PIM Manager network (a machine that reaches the SQL server's private endpoint) -- $(Get-PimScriptDocUrl -Script (Get-PimSupportSqlScriptName))",
        "(b) if another job of this installation carries the SQL admin identity as a user-assigned identity and pulls its image with a user-assigned identity, name it: -TemplateJobName <job> -SqlIdentityClientId <that identity's client id>",
        "(c) ask Invardia support: the installation's database setup job ($TemplateJobName) is what this script copies its identity from, and this installation does not have it in that form"
    )
}

function Get-PimSupportSqlJobCommand {
    # PURE. The two lines a person runs: the download, then the run (framework 12.10 item 11) -- parameters, never a file.
    param([string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup, [string]$SupportAppId)
    $name = Get-PimSupportSqlJobScriptName
    $run = ".\$name.ps1 -TenantId '$TenantId' -SubscriptionId '$SubscriptionId' -ResourceGroup '$ResourceGroup' -SupportAppId '$SupportAppId'"
    return @(Get-PimSupportScriptCommand -Script $name -Run @($run))
}

function Get-PimSupportSqlJobPlan {
    <#
      PURE. From the installation's own database setup job (-Template, the ARM object) to the one-time job: which
      identity, which database, which image, and the whole resource body. Never throws.
      Returns { ok; problem; identityResourceId; identityName; identityClientId; identitySource; pullIdentities;
                sqlServer; sqlDatabase; image; environmentId; location; appRoot; script; resource }.
      ok = $false + problem: the template cannot be used WITHOUT giving some identity a new right -- the caller stops.
    #>
    param(
        [Parameter(Mandatory)][AllowNull()]$Template,
        [Parameter(Mandatory)][string]$TemplateJobName,
        [Parameter(Mandatory)][string]$JobName,
        [Parameter(Mandatory)][string]$SupportAppId,
        [string]$DbUserName = (Get-PimSupportSqlUserDefaultName),
        [string]$SqlIdentityClientId = '',
        # framework SECAUDIT-1a 4b / 4c: standing (as before) | install (the support-session step) | grant | close
        # | consent (OPEN-01: one action the updater decided from Invardia's consent channel)
        [ValidateSet('standing', 'install', 'grant', 'close', 'consent')][string]$Mode = 'standing',
        [int]$SupportHours = 0,
        [string]$Level = 'setup',
        [string]$ConsentLevel = '',
        [string]$Reason = '',
        [string]$TicketNumber = '',
        [string]$OpenedBy = '',
        # mode consent: ensure-read-user | remove-user | open-admin | close-admin; -UntilUtc the end of an open-admin
        [string]$ConsentAction = '',
        [string]$UntilUtc = '',
        [datetime]$NowUtc = [datetime]::UtcNow
    )
    $p = [ordered]@{ ok = $false; problem = ''; identityResourceId = ''; identityName = ''; identityClientId = ''; identitySource = ''; pullIdentities = @()
                     sqlServer = ''; sqlDatabase = ''; image = ''; environmentId = ''; location = ''; appRoot = ''; script = ''; resource = $null; untilUtc = '' }
    try {
        if ($Mode -eq 'grant') {
            if ($SupportHours -lt 1 -or $SupportHours -gt (Get-PimSupportJitMaxHours)) { $p.problem = "the support access may last 1 to $(Get-PimSupportJitMaxHours) hours (asked: $SupportHours)"; return [pscustomobject]$p }
            if ((ConvertTo-PimSupportJitLevel "$Level") -notin @('troubleshoot', 'setup')) { $p.problem = "the level '$Level' is not troubleshoot or setup"; return [pscustomobject]$p }
            $Level = ConvertTo-PimSupportJitLevel "$Level"
            $p.untilUtc = Format-PimSupportJitUtc -Utc $NowUtc.ToUniversalTime().AddHours($SupportHours)
        }
        if ($Mode -eq 'install' -and -not (ConvertTo-PimSupportJitLevel "$ConsentLevel")) { $p.problem = "the consent level '$ConsentLevel' is not none, troubleshoot or setup"; return [pscustomobject]$p }
        if ($Mode -eq 'install') { $ConsentLevel = ConvertTo-PimSupportJitLevel "$ConsentLevel" }
        if ($Mode -eq 'standing' -and "$ConsentLevel".Trim()) {
            # OPEN-01: the read-only user records troubleshoot or setup; 'none' (no user at all) is -InstallSupportAccess -ConsentLevel none
            $ConsentLevel = ConvertTo-PimSupportJitLevel "$ConsentLevel"
            if ($ConsentLevel -notin @('troubleshoot', 'setup')) { $p.problem = "the read-only user records the consent level troubleshoot or setup (asked: '$ConsentLevel'); for no user at all run -InstallSupportAccess -ConsentLevel none"; return [pscustomobject]$p }
        }
        if ($Mode -eq 'consent') {
            if ("$ConsentAction" -notin @('ensure-read-user', 'remove-user', 'open-admin', 'close-admin')) { $p.problem = "the consent action '$ConsentAction' is not ensure-read-user, remove-user, open-admin or close-admin"; return [pscustomobject]$p }
            $ConsentLevel = ConvertTo-PimSupportJitLevel "$ConsentLevel"
            if (-not $ConsentLevel) { $p.problem = 'the consent level is not none, troubleshoot or setup'; return [pscustomobject]$p }
            if ($ConsentAction -eq 'open-admin') {
                # the admin access only with consent setup, and only until an end that lies ahead -- at most 8 h (the procedure checks it again)
                if ($ConsentLevel -ne 'setup') { $p.problem = "an admin access needs the consent level setup (it is '$ConsentLevel')"; return [pscustomobject]$p }
                $uu = ConvertFrom-PimSupportJitUtc "$UntilUtc"
                if (-not $uu -or $uu -le $NowUtc.ToUniversalTime()) { $p.problem = "the end of the admin access ('$UntilUtc') is not a UTC time ahead"; return [pscustomobject]$p }
                $cap = $NowUtc.ToUniversalTime().AddHours((Get-PimSupportJitMaxHours))
                if ($uu -gt $cap) { $uu = $cap }
                $p.untilUtc = Format-PimSupportJitUtc -Utc $uu
            }
        }
        if ("$JobName" -cnotmatch '^[a-z][a-z0-9-]{0,30}[a-z0-9]$') { $p.problem = "'$JobName' is not a job name (lower-case letters, digits and '-', at most 32 characters)"; return [pscustomobject]$p }
        if ("$JobName" -ieq "$TemplateJobName") { $p.problem = "the one-time job cannot have the name of the job it is copied from ('$TemplateJobName')"; return [pscustomobject]$p }
        [void](ConvertTo-PimSupportSqlSid -AppId $SupportAppId)
        Test-PimSupportSqlNames -DbUserName $DbUserName -Role (Get-PimSupportSqlRoleName)
        if (-not $Template -or -not $Template.properties) { $p.problem = "the job '$TemplateJobName' could not be read"; return [pscustomobject]$p }
        $p.environmentId = "$($Template.properties.environmentId)".Trim()
        $p.location = "$($Template.location)".Trim()
        if (-not $p.environmentId -or -not $p.location) { $p.problem = "the job '$TemplateJobName' names no Container Apps environment or no location"; return [pscustomobject]$p }

        $containers = @(@($Template.properties.template.containers) | Where-Object { $_ })
        $c = @($containers | Where-Object { "$($_.name)" -eq $TemplateJobName }) | Select-Object -First 1
        if (-not $c) { $c = $containers | Select-Object -First 1 }
        if (-not $c -or -not "$($c.image)".Trim()) { $p.problem = "the job '$TemplateJobName' has no container image"; return [pscustomobject]$p }
        $p.image = "$($c.image)".Trim()
        $envMap = [ordered]@{}
        foreach ($e in @($c.env)) { if ($e -and "$($e.name)".Trim()) { $envMap["$($e.name)".Trim()] = "$($e.value)" } }
        $p.sqlServer = "$($envMap['PIM_SqlServer'])".Trim()
        $p.sqlDatabase = "$($envMap['PIM_SqlDatabase'])".Trim()
        if (-not $p.sqlDatabase) { $p.sqlDatabase = 'PimPlatform' }
        if ($p.sqlServer -notmatch '^[A-Za-z0-9][A-Za-z0-9.-]{1,250}$') { $p.problem = "the job '$TemplateJobName' does not name the SQL server (its setting PIM_SqlServer)"; return [pscustomobject]$p }
        if ($p.sqlDatabase -notmatch '^[^<>*%&:\\/?\[\]'';]{1,128}$') { $p.problem = "the job '$TemplateJobName' names a database that is not a database name"; return [pscustomobject]$p }

        # ---- the identity: one the template job ALREADY carries, found by its client id. Never a new one.
        $setting = Get-PimSupportSqlJobIdentitySetting
        $cid = "$SqlIdentityClientId".Trim().ToLowerInvariant(); $src = 'named with -SqlIdentityClientId'
        if (-not $cid) { $cid = "$($envMap[$setting])".Trim().ToLowerInvariant(); $src = "the identity $TemplateJobName signs in to the database with (its setting $setting)" }
        if (-not $cid -and $Mode -eq 'close') {
            # 4b: the CLOSE may run as the ENGINE identity (-TemplateJobName <the engine job>): the signed revoke needs no owner
            # right, only EXECUTE. v2 (OPEN-01): the engine no longer opens anything -- a grant runs as the database job only.
            foreach ($es in @('AZURE_CLIENT_ID', 'PIM_ManagedIdentityClientId')) { if ("$($envMap[$es])".Trim()) { $cid = "$($envMap[$es])".Trim().ToLowerInvariant(); $src = "the identity $TemplateJobName runs as (its setting $es)"; break } }
        }
        $ua = ConvertTo-PimSupportSqlJobMap $(if ($Template.identity) { $Template.identity.userAssignedIdentities } else { $null })
        if ($cid -notmatch '^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$') {
            $carried = @(@($ua.Keys) | ForEach-Object { "$(("$_" -split '/')[-1]) (client id $("$($ua[$_].clientId)".Trim()))" })
            $p.problem = "the job '$TemplateJobName' does not say which identity it signs in to the database with (no setting $setting), so there is no identity of this installation this script may use by itself. " +
                         $(if ($carried.Count) { "The user-assigned identities it carries: $($carried -join ', ') -- when one of them is the SQL server's administrator (or a member of the SQL admin group), name it with -SqlIdentityClientId <its client id>" } else { 'It carries no user-assigned identity at all' })
            return [pscustomobject]$p
        }
        $sqlKey = ''
        foreach ($k in @($ua.Keys)) { if ("$($ua[$k].clientId)".Trim().ToLowerInvariant() -eq $cid) { $sqlKey = "$k"; break } }
        if (-not $sqlKey) {
            $p.problem = "the identity $cid is not one of the user-assigned identities of the job '$TemplateJobName' -- this script never attaches an identity the installation's own job does not already carry"
            return [pscustomobject]$p
        }
        $p.identityResourceId = $sqlKey; $p.identityName = ($sqlKey -split '/')[-1]; $p.identityClientId = $cid; $p.identitySource = $src

        # ---- the image pull: only with a user-assigned identity the template job already carries
        $uaBody = [ordered]@{}; $uaBody[$sqlKey] = @{}
        $regs = New-Object System.Collections.Generic.List[object]
        $pull = New-Object System.Collections.Generic.List[string]
        foreach ($r in @(@($Template.properties.configuration.registries) | Where-Object { $_ })) {
            $server = "$($r.server)".Trim(); $ri = "$($r.identity)".Trim()
            if ("$($r.passwordSecretRef)".Trim() -or "$($r.username)".Trim()) {
                $p.problem = "the job '$TemplateJobName' pulls its image from $server with a user name and password -- a one-time job would need a copy of that password, and this script copies no secret"
                return [pscustomobject]$p
            }
            if (-not $ri -or $ri -ieq 'system') {
                $p.problem = "the job '$TemplateJobName' pulls its image from $server with its OWN system identity -- a new job has another identity, which would need a new right on the registry, and this script gives no identity a new right"
                return [pscustomobject]$p
            }
            $pk = ''
            foreach ($k in @($ua.Keys)) { if ("$k" -ieq $ri) { $pk = "$k"; break } }
            if (-not $pk) { $p.problem = "the job '$TemplateJobName' pulls its image from $server with an identity it does not carry ($ri)"; return [pscustomobject]$p }
            if (-not $uaBody.Contains($pk)) { $uaBody[$pk] = @{} }
            if ($pk -ine $sqlKey -and -not $pull.Contains($pk)) { $pull.Add($pk) }
            $regs.Add([ordered]@{ server = $server; identity = $pk })
        }
        $p.pullIdentities = @($pull.ToArray())

        # ---- where the image keeps the product: read off the template job's own start command
        $root = Get-PimSupportSqlJobDefaultAppRoot
        foreach ($a in @($c.args)) { if ("$a" -match '^(?<root>[A-Za-z0-9_./:~ -]+)/tools/pim-engine/[A-Za-z0-9_.-]+\.ps1$') { $root = $Matches['root']; break } }
        $p.appRoot = $root
        $p.script = Get-PimSupportSqlJobScript -AppRoot $root
        $encoded = ConvertTo-PimSupportSqlJobCommand -Script $p.script

        $envList = @(
            @{ name = 'PIM_SqlServer'; value = $p.sqlServer }
            @{ name = 'PIM_SqlDatabase'; value = $p.sqlDatabase }
            @{ name = 'PIM_SUPPORTSQL_APP_ID'; value = "$SupportAppId".Trim().ToLowerInvariant() }
            @{ name = 'PIM_SUPPORTSQL_DB_USER'; value = "$DbUserName" }
            @{ name = 'PIM_SUPPORTSQL_MI_CLIENT_ID'; value = $cid }
        )
        $timeout = 604800
        if ($Mode -ne 'standing') {
            $envList += @(
                @{ name = 'PIM_SUPPORTSQL_MODE'; value = $Mode }
                @{ name = 'PIM_SUPPORTSQL_JIT_OPENED_BY'; value = (ConvertTo-PimSupportJitText -Text $OpenedBy -Max 120) }
            )
        }
        if ($Mode -eq 'install') { $envList += @(@{ name = 'PIM_SUPPORTSQL_CONSENT_LEVEL'; value = "$ConsentLevel" }) }
        if ($Mode -eq 'standing' -and "$ConsentLevel".Trim()) { $envList += @(@{ name = 'PIM_SUPPORTSQL_CONSENT_LEVEL'; value = "$ConsentLevel" }) }
        if ($Mode -eq 'consent') {
            # OPEN-01: one short run -- the action, Invardia's consent level, the end of an admin access; the job ends itself
            $envList += @(
                @{ name = 'PIM_SUPPORTSQL_CONSENT_ACTION'; value = "$ConsentAction" }
                @{ name = 'PIM_SUPPORTSQL_CONSENT_LEVEL'; value = "$ConsentLevel" }
                @{ name = 'PIM_SUPPORTSQL_JIT_UNTIL'; value = "$($p.untilUtc)" }
                @{ name = 'PIM_SUPPORTSQL_JIT_REASON'; value = (ConvertTo-PimSupportJitText -Text $Reason -Max 120) }
                @{ name = 'PIM_SUPPORTSQL_JIT_TICKET'; value = (ConvertTo-PimSupportJitText -Text $TicketNumber -Max 40) }
            )
            $timeout = 1800
        }
        if ($Mode -eq 'grant') {
            # the job holds until the end and then takes the access back; the platform ends it at the latest an hour after
            $envList += @(
                @{ name = 'PIM_SUPPORTSQL_JIT_LEVEL'; value = "$Level" }
                @{ name = 'PIM_SUPPORTSQL_JIT_HOURS'; value = "$([int]$SupportHours)" }
                @{ name = 'PIM_SUPPORTSQL_JIT_REASON'; value = (ConvertTo-PimSupportJitText -Text $Reason -Max 120) }
                @{ name = 'PIM_SUPPORTSQL_JIT_TICKET'; value = (ConvertTo-PimSupportJitText -Text $TicketNumber -Max 40) }
            )
            $timeout = ([int]$SupportHours * 3600) + 3600
        }
        $cfg = [ordered]@{ triggerType = 'Manual'; replicaTimeout = $timeout; replicaRetryLimit = 0; manualTriggerConfig = @{ parallelism = 1; replicaCompletionCount = 1 } }
        if ($regs.Count) { $cfg['registries'] = @($regs.ToArray()) }
        $props = [ordered]@{ environmentId = $p.environmentId }
        if ("$($Template.properties.workloadProfileName)".Trim()) { $props['workloadProfileName'] = "$($Template.properties.workloadProfileName)".Trim() }
        $props['configuration'] = $cfg
        $props['template'] = @{ containers = @(@{
            name      = $JobName
            image     = $p.image
            command   = @('pwsh')
            args      = @('-NoProfile', '-NonInteractive', '-EncodedCommand', $encoded)
            env       = @($envList)
            resources = @{ cpu = 0.5; memory = '1.0Gi' }
        }) }
        $tags = @{}; $tags[(Get-PimSupportSqlJobTagName)] = (Get-PimSupportSqlJobTagValue)
        if ($p.untilUtc -and $Mode -eq 'grant') { $tags[(Get-PimSupportSqlJobUntilTagName)] = $p.untilUtc }   # a consent run never holds: it ends itself
        $p.resource = [ordered]@{ location = $p.location; tags = $tags; identity = [ordered]@{ type = 'UserAssigned'; userAssignedIdentities = $uaBody }; properties = $props }
        $p.ok = $true
    } catch { $p.ok = $false; $p.problem = (("$($_.Exception.Message)" -split "`n")[0]).Trim() }
    return [pscustomobject]$p
}

function Invoke-PimSupportSqlJobGrant {
    <#
      The one-time job, end to end (PIM REQUIREMENTS 100.116, decision 31):
        1. read the installation's database setup job; plan the one-time job from it (identity, database, image). No
           usable identity -> STOP with the options; nothing is changed
        2. read: is there already a job of the one-time name (a leftover of a killed run carries this script's tag; a
           job without the tag is NOT touched -> stop), and does the Support app exist in this tenant (Microsoft Graph)
        3. create the job (the tag, the identity the setup job already carries, the script) and wait until it is there
        4. start it, wait for the execution to end (bounded)
        5. read the execution's console lines from the environment's Log Analytics workspace (bounded; they arrive late)
        6. finally: remove the job and read back that it is gone -- also after a failed step
      PASS needs: the execution Succeeded (the job exits 0 only after it READ BACK the user and its role) and no result
      line that says otherwise. -WhatIfOnly: steps 1 and 2 are READ, the rest is printed. Nothing is written.
      TIME-LIMITED (-Mode grant -SupportHours, SECAUDIT-1a): the job keeps running until that end and takes the access back by
      itself, so this run waits only for the job's RESULT line (the grant, read back by the job) and then LEAVES the job
      running until it has done that. A leftover that still holds a time-limited access (its tag
      pim-support-until is in the future) is removed only by another time-limited run, whose job then takes over the
      later of the two ends; a standing run stops instead.
      Never throws. Returns { ok; exit (0 done, 1 not done); whatIf; plan; leftover; jobCreated; jobRemoved; jobKept;
      execution; status; logLines; result; warnings; problems }.
    #>
    param(
        [Parameter(Mandatory)][scriptblock]$Arm,
        [scriptblock]$Graph,
        [scriptblock]$Logs,
        [Parameter(Mandatory)][string]$SubscriptionId,
        [Parameter(Mandatory)][string]$ResourceGroup,
        [Parameter(Mandatory)][string]$SupportAppId,
        [string]$TemplateJobName = (Get-PimSupportSqlJobTemplateName),
        [string]$JobName = (Get-PimSupportSqlJobDefaultName),
        [string]$DbUserName = (Get-PimSupportSqlUserDefaultName),
        [string]$SqlIdentityClientId = '',
        [int]$TimeoutSeconds = 600,
        [int]$PollSeconds = 10,
        [int]$LogWaitSeconds = 180,
        [int]$ReadBackTries = 30,
        [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds },
        [ValidateSet('standing', 'install', 'grant', 'close', 'consent')][string]$Mode = 'standing',
        [int]$SupportHours = 0,
        [string]$Level = 'setup',
        [string]$ConsentLevel = '',
        [string]$Reason = '',
        [string]$TicketNumber = '',
        [string]$OpenedBy = '',
        [string]$ConsentAction = '',
        [string]$UntilUtc = '',
        [datetime]$NowUtc = [datetime]::UtcNow,
        [switch]$WhatIfOnly
    )
    $api = Get-PimSupportSqlJobAcaApi
    $jit = ($Mode -eq 'grant')
    $role = Get-PimSupportJitAdminRole          # the role a time-limited setup session adds (and takes back)
    $readRole = Get-PimSupportSqlRoleName       # OPEN-01: the Support app's only standing role
    $tagName = Get-PimSupportSqlJobTagName; $tagValue = Get-PimSupportSqlJobTagValue
    $rgPath = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup"
    $jobPath = "$rgPath/providers/Microsoft.App/jobs/$JobName"
    $tplPath = "$rgPath/providers/Microsoft.App/jobs/$TemplateJobName"
    $notFound = '(?i)HTTP 404\b|ResourceNotFound|was not found|NotFound'
    $warnings = New-Object System.Collections.Generic.List[string]
    $problems = New-Object System.Collections.Generic.List[string]
    $res = [ordered]@{ ok = $false; exit = 1; whatIf = [bool]$WhatIfOnly; plan = $null; leftover = $false; jobCreated = $false; jobRemoved = $false; jobKept = $false
                       execution = ''; status = ''; logLines = @(); result = $null; warnings = @(); problems = @() }
    $say = { param([string]$m, [string]$c = 'Gray') Write-Host "  $m" -ForegroundColor $c }
    $first = { param($e) (("$($e.Exception.Message)" -split "`n")[0]).Trim() }
    $get = {
        param([string]$P)
        try { return (& $Arm 'GET' "${P}?api-version=$api" $null) }
        catch { if ("$($_.Exception.Message)" -match $notFound) { return $null }; throw }
    }
    $finish = {
        $res.warnings = @($warnings.ToArray()); $res.problems = @($problems.ToArray())
        $res.exit = if ($problems.Count) { 1 } else { 0 }
        $res.ok = ($res.exit -eq 0)
        return [pscustomobject]$res
    }
    $remove = {
        # DELETE the one-time job and read back until it is gone. '' = gone; otherwise why it is not.
        $why = ''
        for ($i = 0; $i -lt [Math]::Max(1, $ReadBackTries); $i++) {
            if ($i -eq 0 -or $i -eq 5) {
                try { [void](& $Arm 'DELETE' "${jobPath}?api-version=$api" $null) }
                catch { if ("$($_.Exception.Message)" -notmatch $notFound) { $why = & $first $_ } }
            }
            try { if (-not (& $get $jobPath)) { return '' } } catch { $why = & $first $_ }
            & $Sleep 5
        }
        if ($why) { return $why }
        return 'it is still there'
    }
    $options = "Options:`n    " + (@(Get-PimSupportSqlJobOptions -TemplateJobName $TemplateJobName) -join "`n    ")

    # ---- 1. the installation's own database setup job, and the plan --------------------------------------------------
    $tpl = $null
    try { $tpl = & $get $tplPath }
    catch { $problems.Add("the job '$TemplateJobName' could not be read in resource group '$ResourceGroup': $(& $first $_) -- nothing was changed"); return (& $finish) }
    if (-not $tpl) {
        $problems.Add("this installation has no job '$TemplateJobName' in resource group '$ResourceGroup' (subscription $SubscriptionId). That job is where an installation with a private database keeps the identity that may create a database user from inside; without it this script has no identity it may use, and it gives no identity a new right. Nothing was changed.`n  $options")
        return (& $finish)
    }
    $plan = Get-PimSupportSqlJobPlan -Template $tpl -TemplateJobName $TemplateJobName -JobName $JobName -SupportAppId $SupportAppId -DbUserName $DbUserName -SqlIdentityClientId $SqlIdentityClientId `
                -Mode $Mode -SupportHours $SupportHours -Level $Level -ConsentLevel $ConsentLevel -Reason $Reason -TicketNumber $TicketNumber -OpenedBy $OpenedBy -NowUtc $NowUtc `
                -ConsentAction $ConsentAction -UntilUtc $UntilUtc
    $res.plan = $plan
    if (-not $plan.ok) { $problems.Add("$($plan.problem). Nothing was changed.`n  $options"); return (& $finish) }
    $sid = ConvertTo-PimSupportSqlSid -AppId $SupportAppId
    & $say "database: $($plan.sqlServer) / $($plan.sqlDatabase) (read from the job $TemplateJobName)"
    & $say "identity: $($plan.identityName) (client id $($plan.identityClientId)) -- $($plan.identitySource). It is used as it is: no role, no group membership and no permission is given to any identity."
    if (@($plan.pullIdentities).Count) { & $say "image pull: $((@($plan.pullIdentities) | ForEach-Object { ($_ -split '/')[-1] }) -join ', ') (the identity $TemplateJobName pulls its image with)" }
    & $say "image: $($plan.image) (the image of $TemplateJobName); environment: $(($plan.environmentId -split '/')[-1])"

    # ---- 2. what is there: a job of the one-time name, the Support app ------------------------------------------------
    try {
        $old = & $get $jobPath
        if ($old) {
            $tags = ConvertTo-PimSupportSqlJobMap $old.tags
            if ("$($tags[$tagName])" -ne $tagValue) {
                $problems.Add("a job named '$JobName' is already in resource group '$ResourceGroup' and was not made by this script (it does not carry the tag $tagName = $tagValue) -- it is not touched. Run again with -JobName <another name>. Nothing was changed.")
                return (& $finish)
            }
            # a leftover that still holds a time-limited access is the job that takes it back: only a time-limited run may
            # replace it (its job takes over the later end); a standing run leaves it as it is and stops
            $oldUntil = ConvertFrom-PimSupportJitUtc -Value "$($tags[(Get-PimSupportSqlJobUntilTagName)])"
            if ($oldUntil -and $oldUntil -gt $NowUtc.ToUniversalTime() -and -not $jit) {
                $problems.Add("the job '$JobName' is running a time-limited support access that ends at $(Format-PimSupportJitUtc -Utc $oldUntil) and takes it back then -- it is not touched. Run again after that time. Nothing was changed.")
                return (& $finish)
            }
            $res.leftover = $true
        }
    } catch { $problems.Add("could not read whether a job '$JobName' is already there: $(& $first $_) -- nothing was changed"); return (& $finish) }
    if ($Graph) {
        try {
            $f = [uri]::EscapeDataString("appId eq '$("$SupportAppId".Trim())'")
            $sp = @((& $Graph 'GET' "/servicePrincipals?`$select=id,appId,displayName&`$filter=$f" $null).value | Where-Object { $_ }) | Select-Object -First 1
            if (-not $sp -or -not "$($sp.id)".Trim()) {
                $problems.Add("the application $SupportAppId has no service principal in this tenant -- create the Invardia Support app in this tenant first, or check the id. Nothing was changed.")
                return (& $finish)
            }
            & $say "Invardia Support app: '$($sp.displayName)' ($SupportAppId) exists in this tenant"
        } catch { $problems.Add("the Invardia Support app could not be looked up in this tenant (Microsoft Graph): $(& $first $_) -- a database owner is not created for an id that could not be checked. Nothing was changed."); return (& $finish) }
    }

    if ($WhatIfOnly) {
        if ($res.leftover) { Write-Host "What if: remove the job '$JobName' a killed run of this script left behind (it carries the tag $tagName = $tagValue)" }
        Write-Host "What if: create the one-time job '$JobName' in the environment $(($plan.environmentId -split '/')[-1]), running as $($plan.identityName), with the tag $tagName = $tagValue"
        if ($Mode -eq 'install') {
            Write-Host "What if: start it once. In the database $($plan.sqlDatabase) it records the customer's consent level '$ConsentLevel' for the Support app (SID $sid), gives the Support app's user [$DbUserName] read-only access, and installs the signed support access procedures (they take no user as a parameter); then it reads all of it back"
            Write-Host "What if: read the execution's result and its log lines, then remove the job '$JobName' and read back that it is gone"
        } elseif ($Mode -eq 'consent') {
            Write-Host "What if: start it once. It first takes back any time-limited support access whose end has passed"
            Write-Host "What if: in the database $($plan.sqlDatabase) it applies '$ConsentAction' for the consent level '$ConsentLevel' Invardia gave$(if ($plan.untilUtc) { " (admin until $($plan.untilUtc))" }), then reads the support access state back"
            Write-Host "What if: read the execution's result, then remove the job '$JobName' and read back that it is gone"
        } elseif ($Mode -eq 'close') {
            Write-Host "What if: start it once. It first takes back any time-limited support access whose end has passed"
            Write-Host "What if: in the database $($plan.sqlDatabase) it closes every open time-limited support access now: the roles the grant added are taken back, the Support app's open sessions end, the read-only access stays"
            Write-Host "What if: read the execution's result and its log lines, then remove the job '$JobName' and read back that it is gone"
        } elseif ($jit) {
            Write-Host "What if: start it once. It first takes back any time-limited support access whose end has passed"
            Write-Host "What if: in the database $($plan.sqlDatabase) it asks for level '$Level' for $SupportHours hour(s); the level given is the lower of that and the customer's consent; for $role the end ($($plan.untilUtc)) is recorded with the role; a role the user held before is never taken away"
            Write-Host "What if: read the job's result, then leave the job running: at $($plan.untilUtc) it takes $role back by itself (the read-only access stays) and ends"
        } else {
            Write-Host "What if: start it once. It first takes back any time-limited support access whose end has passed"
            Write-Host "What if: in the database $($plan.sqlDatabase) it runs the support access step (consent '$(if ("$ConsentLevel".Trim()) { (ConvertTo-PimSupportJitLevel "$ConsentLevel") } else { 'as recorded, else troubleshoot' })'): the user [$DbUserName] from the Support app's client id (SID $sid) when no user has that id, in $readRole only (read-only); an existing user of the Support app is reused whatever its name; no database owner role and no SQL admin group membership is given"
            Write-Host "What if: read the execution's result and its log lines, then remove the job '$JobName' and read back that it is gone"
        }
        Write-Host 'What if: the script the job would run (built from the same functions Grant-PimSupportSqlAccess.ps1 uses):'
        foreach ($line in @($plan.script -split "`n")) { Write-Host "    | $($line.TrimEnd())" }
        return (& $finish)
    }

    # ---- a leftover of a killed run goes first (its tag says it is this script's) --------------------------------------
    if ($res.leftover) {
        $left = & $remove
        if ($left) { $problems.Add("the job '$JobName' a killed run left behind could not be removed ($left) -- nothing else was changed. Remove it: Azure portal > resource group $ResourceGroup > $JobName > Delete, then run this script again."); return (& $finish) }
        & $say "removed: the job '$JobName' a killed run of this script left behind (read back)" 'Yellow'
    }

    $final = @('Succeeded', 'Failed', 'Degraded', 'Stopped')
    try {
        try {
            # ---- 3. create the job
            $res.jobCreated = $true     # set BEFORE the call: a job that was half created is still removed
            [void](& $Arm 'PUT' "${jobPath}?api-version=$api" $plan.resource)
            $state = ''
            $tries = [Math]::Max(1, [int][Math]::Ceiling(120 / [double][Math]::Max(1, $PollSeconds)))
            for ($i = 0; $i -lt $tries; $i++) {
                $j = & $get $jobPath
                $state = if ($j) { "$($j.properties.provisioningState)".Trim() } else { 'NotFound' }
                if ($state -in @('Succeeded', 'Failed', 'Canceled')) { break }
                & $Sleep $PollSeconds
            }
            if ($state -ne 'Succeeded') { throw "the job '$JobName' was not created (state: $state)" }
            & $say "created: the one-time job '$JobName' (running as $($plan.identityName); $(if ($jit) { "it ends after it has taken the access back at $($plan.untilUtc)" } else { 'removed again at the end' }))" 'Yellow'

            # ---- 4. start it once and wait
            $started = & $Arm 'POST' "${jobPath}/start?api-version=$api" @{}
            $exec = if ($started) { "$($started.name)".Trim() } else { '' }
            if (-not $exec) { throw "the job '$JobName' did not start (no execution was returned)" }
            $res.execution = $exec
            & $say "started: execution $exec -- waiting (at most $TimeoutSeconds seconds)"
            $tries = [Math]::Max(1, [int][Math]::Ceiling($TimeoutSeconds / [double][Math]::Max(1, $PollSeconds)))
            $status = ''; $lastErr = ''
            # time-limited: the job keeps running until the end, so the wait is for its RESULT line, read while it runs
            $ws = ''; $jitLines = @(); $jitRefused = 0
            if ($jit -and $Logs) { try { $envObj = & $get $plan.environmentId; if ($envObj) { $ws = "$($envObj.properties.appLogsConfiguration.logAnalyticsConfiguration.customerId)".Trim() } } catch { $ws = '' } }
            for ($i = 0; $i -lt $tries; $i++) {
                & $Sleep $PollSeconds
                try { $x = & $get "$jobPath/executions/$exec"; $status = if ($x) { "$($x.properties.status)".Trim() } else { '' } } catch { $lastErr = & $first $_ }
                if ($status -in $final) { break }
                if ($jit -and $ws -and $jitRefused -lt 2) {
                    try { $jitLines = @(& $Logs $ws $exec | ForEach-Object { "$_" }); $jitRefused = 0 } catch { $jitLines = @(); $jitRefused++ }
                    if (@($jitLines | Where-Object { $_ -match '\[supportsql\] RESULT ' }).Count) { break }
                }
            }
            $res.status = $status

            # ---- 5. the console lines (they reach the workspace late; a missing log never turns a result around)
            $lines = @()
            if ($jit -and $status -notin $final) { $lines = @($jitLines) }
            elseif ($Logs -and $status -in $final) {
                if (-not $ws) { try { $envObj = & $get $plan.environmentId; if ($envObj) { $ws = "$($envObj.properties.appLogsConfiguration.logAnalyticsConfiguration.customerId)".Trim() } } catch { $ws = '' } }
                if ($ws) {
                    $ltries = [Math]::Max(1, [int][Math]::Ceiling($LogWaitSeconds / 20.0))
                    $refused = 0
                    for ($i = 0; $i -lt $ltries; $i++) {
                        try { $lines = @(& $Logs $ws $exec | ForEach-Object { "$_" }); $refused = 0 } catch { $lines = @(); $refused++ }
                        if (@($lines | Where-Object { $_ -match '\[supportsql\] RESULT ' }).Count) { break }
                        if ($refused -ge 2) { break }     # a read that is refused twice in a row (no reader right) is not asked again
                        if ($i -lt $ltries - 1) { & $Sleep 20 }
                    }
                }
            }
            $log = ConvertFrom-PimSupportSqlJobLog -Lines $lines
            $res.logLines = @($log.lines); $res.result = $log.result
            if (@($log.lines).Count) { & $say "the job's log ($(@($log.lines).Count) line(s)):"; foreach ($ln in @($log.lines)) { Write-Host "    | $ln" -ForegroundColor DarkGray } }
            else { & $say "the job's log could not be read (it reaches the environment's Log Analytics workspace a few minutes after the run: ContainerAppConsoleLogs_CL, ContainerGroupName_s startswith '$exec')" 'DarkGray' }

            # ---- the verdict
            $r = $log.result
            $revokeLine = @($log.lines | Where-Object { $_ -match '\[supportsql\] REVOKE \{' }) | Select-Object -Last 1
            if ($jit -and $status -notin $final) {
                # the job holds the time-limited access and takes it back at the end by itself: it is NOT stopped or removed
                $res.jobKept = $true
                if ($r -and [bool]$r.ok) {
                    if ("$($r.state)" -eq 'read-only') {
                        & $say "the level given is read-only (asked '$($r.requested)', consented '$($r.consented)'): nothing was added; the job ends by itself" 'Green'
                    } elseif ("$($r.state)" -eq 'pre-existing') {
                        & $say "the Support app's database user already held $role before this grant -- it is recorded until $($r.untilUtc) and is NOT taken away then" 'Green'
                    } else {
                        & $say "the Support app's database user (SID $sid): $role until $($r.untilUtc) (asked '$($r.requested)', consented '$($r.consented)')$(if ("$($r.state)" -eq 'extended') { ' -- an open access was extended to the later end' }); read-only access kept (read back by the job)" 'Green'
                        & $say "the job '$JobName' keeps running and takes $role back at $($r.untilUtc) by itself; the read-only access stays" 'Green'
                    }
                } elseif ($r) {
                    $problems.Add("the job's result line says the time-limited access was not put in place ($($r.problem)) -- treated as NOT done")
                } else {
                    $problems.Add("the job is running (execution $exec) but its result line could not be read within $TimeoutSeconds seconds, so the time-limited access is NOT confirmed. The job is left running: it takes back whatever it gave at $($plan.untilUtc) by itself.")
                }
            } elseif ($Mode -in @('install', 'close', 'consent') -and $status -eq 'Succeeded' -and $r -and [bool]$r.ok) {
                if ($Mode -eq 'consent') { & $say "consent: '$($r.action)' applied and read back by the job (consent '$($r.consented)', read-only $($r.readOnly), admin open $($r.jitOpen)$(if ("$($r.jitUntil)") { " until $($r.jitUntil)" }))" 'Green' }
                elseif ($Mode -eq 'install') { & $say "installed: the signed support access procedures (read back by the job: current, signed, private key removed, ALTER denied); consent '$($r.consented)'" 'Green' }
                else { & $say "closed: $($r.closed) open support access grant(s) (only roles the grant added were taken back; $($r.sessionsEnded) session(s) ended)$(if ("$($r.state)" -eq 'not-installed') { ' -- the time-limited access is not installed here' })" 'Green' }
            } elseif ($jit -and $status -eq 'Succeeded' -and $revokeLine) {
                & $say "the job gave the time-limited access and has already taken it back (its end has passed): $($revokeLine.Trim())" 'Green'
            } elseif ($status -eq 'Succeeded' -and $r -and -not [bool]$r.ok) {
                $problems.Add("the execution $exec ended Succeeded but its result line says it did not put the user in place ($($r.problem)) -- treated as NOT done")
            } elseif ($status -eq 'Succeeded') {
                if ($r) {
                    $what = switch ("$($r.state)") { 'created' { 'created' } 'in-place' { 'was already there' } default { 'in place' } }
                    & $say "database user [$($r.userName)] (the Support app's client id, SID $sid): $what; in $readRole only, consent '$($r.consented)' (read back by the job)" 'Green'
                    # OPEN-01: what an EARLIER version gave is said (a WARNING), never kept as "in place", never removed here
                    $lt = Get-PimSupportSqlLegacyText -Legacy @(@($r.legacy) | Where-Object { "$_".Trim() }) -SessionOpen ([bool]$r.sessionOpen)
                    if ($lt) { $warnings.Add($lt) }
                } else {
                    $warnings.Add("the execution $exec ended Succeeded, and the job ends that way only after it read the user and its role back; its log lines could not be read here, so the user's name and whether it was created or already there are not shown")
                }
            } elseif ($status -in $final) {
                $problems.Add("the one-time job ended '$status' (execution $exec)$(if ($r -and "$($r.problem)") { ": $($r.problem)" } elseif (-not @($log.lines).Count) { ' and wrote no log line this run could read -- when the image could not be pulled or the job could not start, there is none' }). The database user was NOT confirmed.")
            } else {
                $problems.Add("the one-time job did not end within $TimeoutSeconds seconds (execution $exec, last state '$status'$(if ($lastErr) { ", last read: $lastErr" })). The database user was NOT confirmed.")
                try { [void](& $Arm 'POST' "${jobPath}/executions/$exec/stop?api-version=$api" @{}) } catch { }
            }
        } catch { $problems.Add("the step stopped: $(& $first $_)") }
    } finally {
        # ---- 6. the job is removed and read back -- also after a failed step. NOT while it holds a time-limited access:
        # it takes that back at the end by itself and then ends.
        if ($res.jobKept) {
            $warnings.Add("the one-time job '$JobName' stays in resource group $ResourceGroup until $($plan.untilUtc): it takes the time-limited access back then and ends. The next run of this script removes it.")
        } elseif ($res.jobCreated) {
            $left = & $remove
            if (-not $left) { $res.jobRemoved = $true; & $say "removed: the one-time job '$JobName' (read back: it is gone)" 'Green' }
            else { $problems.Add("the one-time job '$JobName' is STILL in resource group $ResourceGroup ($left). It carries the SQL admin identity and does nothing until it is started; remove it: Azure portal > resource group $ResourceGroup > $JobName > Delete -- or run this script again, which removes it first.") }
        }
    }
    return (& $finish)
}

# ===== END inlined helper: _PimSupportSqlJob.ps1 =====
$null = Start-PimScriptRun -Script 'Invoke-PimSupportSqlAccessJob'
$script:ssjRc = 1
try {
$tid = "$TenantId".Trim().ToLowerInvariant(); $sub = "$SubscriptionId".Trim().ToLowerInvariant()
if ($JobName -ieq $TemplateJobName) { throw "Invoke-PimSupportSqlAccessJob: -JobName and -TemplateJobName are the same ('$JobName') -- the one-time job is created and removed, the installation's own job is only read. Nothing was touched." }

Write-Host ('=' * 78) -ForegroundColor Cyan
Write-Host " PIM MANAGER -- INVARDIA SUPPORT: DATABASE ACCESS FROM INSIDE (PRIVATE DATABASE)  ($ResourceGroup)$(if ($WhatIfPreference) { '   PREVIEW' })" -ForegroundColor Cyan
Write-Host ('=' * 78) -ForegroundColor Cyan

# ---- sign-in: the Support app's session in this window, else the person's browser (asserted: this tenant, this subscription)
$sessionApp = ''
if (-not ($Arm -and $Graph)) {
    $who = Get-PimSignedInIdentity -TenantId $tid -SubscriptionId $sub
    if (-not $who.ok) { throw "Invoke-PimSupportSqlAccessJob: REFUSED (nothing was touched) -- $($who.reason)" }
    $sessionApp = "$($who.supportAppId)".Trim().ToLowerInvariant()
    Write-Host "  $($who.reason)" -ForegroundColor DarkGray
}
$app = "$SupportAppId".Trim().ToLowerInvariant()
if (-not $app) { $app = $sessionApp }
if (-not $app) { throw 'Invoke-PimSupportSqlAccessJob: pass -SupportAppId <the Invardia Support app''s client id> (it is only known by itself in the Support app''s own session). Nothing was touched.' }
if ($sessionApp -and $sessionApp -ne $app) { throw "Invoke-PimSupportSqlAccessJob: this window is the session of the Support app $sessionApp, but -SupportAppId names $app -- REFUSED (the right would go to another application). Nothing was touched." }
Write-Host "  Invardia Support app: $app" -ForegroundColor DarkGray

# ---- the callers (REST only) ------------------------------------------------------------------------------------------
# PLAIN scriptblocks over script-level functions, never a bound closure: a closure runs in its own module scope and
# cannot see the functions this script loaded (the token client).
$script:ssjTenant = $tid
function Invoke-SsjRest {
    param([string]$Base, [string]$Resource, [string]$Method = 'GET', [string]$Path, $Body)
    $WhatIfPreference = $false   # the reads of a preview are real; every write is gated before it gets here
    $tok = "$(Get-PimRestToken -Resource $Resource -TenantId $script:ssjTenant)".Trim()
    if (-not $tok) { throw "no token for $Resource in tenant $($script:ssjTenant)" }
    $a = @{ Method = $Method; Uri = $(if ($Path -match '^https://') { $Path } else { "$Base$Path" }); Headers = @{ Authorization = "Bearer $tok" } }
    if ($null -ne $Body) { $a['Body'] = ($Body | ConvertTo-Json -Depth 12 -Compress); $a['ContentType'] = 'application/json' }
    try { return (Invoke-RestMethod @a) }
    catch {
        $code = 0; try { $code = [int]$_.Exception.Response.StatusCode } catch { $code = 0 }
        throw "$Method $Path -> HTTP $code : $((("$($_.ErrorDetails.Message) $($_.Exception.Message)") -replace '\s+', ' ').Trim())"
    }
}
function Get-SsjLogLines {
    # The console lines of one execution, from the environment's Log Analytics workspace. A read; never part of the verdict.
    param([string]$WorkspaceId, [string]$Execution)
    $q = Get-PimSupportSqlJobLogQuery -Execution $Execution
    $r = Invoke-SsjRest -Base 'https://api.loganalytics.io' -Resource 'https://api.loganalytics.io' -Method 'POST' -Path "/v1/workspaces/$WorkspaceId/query" -Body @{ query = $q; timespan = 'P1D' }
    $out = New-Object System.Collections.Generic.List[string]
    foreach ($t in @(@($r.tables) | Select-Object -First 1)) {
        $at = 0; $cols = @($t.columns)
        for ($i = 0; $i -lt $cols.Count; $i++) { if ("$($cols[$i].name)" -eq 'Log_s') { $at = $i } }
        foreach ($row in @($t.rows)) { $out.Add("$(@($row)[$at])") }
    }
    return @($out.ToArray())
}
if (-not $Arm) { $Arm = { param([string]$Method = 'GET', [string]$Path, $Body) Invoke-SsjRest -Base 'https://management.azure.com' -Resource 'https://management.azure.com' -Method $Method -Path $Path -Body $Body } }
if (-not $Graph) { $Graph = { param([string]$Method = 'GET', [string]$Path, $Body) Invoke-SsjRest -Base 'https://graph.microsoft.com/v1.0' -Resource 'https://graph.microsoft.com' -Method $Method -Path $Path -Body $Body } }
if (-not $Logs) { $Logs = { param([string]$WorkspaceId, [string]$Execution) Get-SsjLogLines -WorkspaceId $WorkspaceId -Execution $Execution } }

# ---- which step: the standing access (as before), the support-session install, open, or close ------------------------
$steps = @(@($InstallSupportAccess, $CloseSupportAccess, ($SupportHours -gt 0)) | Where-Object { $_ })
if ($steps.Count -gt 1) { throw 'Invoke-PimSupportSqlAccessJob: -InstallSupportAccess, -SupportHours and -CloseSupportAccess are separate steps -- pass one. Nothing was touched.' }
$mode = if ($InstallSupportAccess) { 'install' } elseif ($CloseSupportAccess) { 'close' } elseif ($SupportHours -gt 0) { 'grant' } else { 'standing' }
if ($mode -eq 'install' -and -not $ConsentLevel) { throw 'Invoke-PimSupportSqlAccessJob: -InstallSupportAccess needs -ConsentLevel none, troubleshoot or setup (the level the customer consents to). Nothing was touched.' }
if ($mode -eq 'grant') { Write-Host "  time-limited: level '$Level' for $SupportHours hour(s) (never above the consented level), taken back by the job at the end" -ForegroundColor DarkGray }
$openedBy = if ($sessionApp) { "Invardia Support app $sessionApp" } elseif ($who -and "$($who.userName)".Trim()) { "$($who.userName)".Trim() } else { '' }
$what = switch ($mode) {
    'install' { "create, run once and remove the job '$JobName', which records the consent level '$ConsentLevel' for the Invardia Support app $app and installs the time-limited support access" }
    'close'   { "create, run once and remove the job '$JobName', which ends every open time-limited support access" }
    'grant'   { "create and start the job '$JobName', which gives the Invardia Support app $app level '$Level' (at most the consented level) for $SupportHours hour(s) and takes it back then" }
    default   { "create, run once and remove the job '$JobName', which gives the Invardia Support app $app its read-only database user (pim_support_read only) from inside the installation" }
}
$whatIfOnly = -not $PSCmdlet.ShouldProcess("resource group $ResourceGroup", $what)
# OPEN-06: the installation's database job is ca-pim-dbinit (today's name) or caj-pim-dbinit (an installation made with the
# new names, or created by the updater there). Not named with -TemplateJobName: the first of the two that exists is read.
if (-not $PSBoundParameters.ContainsKey('TemplateJobName')) {
    foreach ($tn in @('ca-pim-dbinit', 'caj-pim-dbinit')) {
        $tFound = $null
        try { $tFound = & $Arm 'GET' "/subscriptions/$sub/resourceGroups/$ResourceGroup/providers/Microsoft.App/jobs/${tn}?api-version=2024-03-01" $null } catch { $tFound = $null }
        if ($tFound) { $TemplateJobName = $tn; break }
    }
    if ($JobName -ieq $TemplateJobName) { throw "Invoke-PimSupportSqlAccessJob: -JobName and -TemplateJobName are the same ('$JobName') -- the one-time job is created and removed, the installation's own job is only read. Nothing was touched." }
    Write-Host "  the installation's database job: $TemplateJobName" -ForegroundColor DarkGray
}
$ja = @{ Arm = $Arm; Graph = $Graph; Logs = $Logs; SubscriptionId = $sub; ResourceGroup = $ResourceGroup; SupportAppId = $app; TemplateJobName = $TemplateJobName; JobName = $JobName
         DbUserName = $DbUserName; SqlIdentityClientId = $SqlIdentityClientId; TimeoutSeconds = $TimeoutSeconds; PollSeconds = $PollSeconds; LogWaitSeconds = $LogWaitSeconds; WhatIfOnly = $whatIfOnly
         Mode = $mode; SupportHours = $SupportHours; Level = $Level; ConsentLevel = $ConsentLevel; Reason = $Reason; TicketNumber = $TicketNumber; OpenedBy = $openedBy }
if ($Sleep) { $ja['Sleep'] = $Sleep }
$r = Invoke-PimSupportSqlJobGrant @ja

foreach ($w in @($r.warnings)) { Write-Host "  WARNING: $w" -ForegroundColor Yellow }
foreach ($p in @($r.problems)) { Write-Host "  NOT DONE: $p" -ForegroundColor Red }
Write-Host ''
if ($r.whatIf) { Write-Host "RESULT: preview only -- nothing was changed$(if (@($r.problems).Count) { ' (see NOT DONE above)' })." -ForegroundColor DarkYellow }
elseif ($r.exit -ne 0) {
    $tail = if ($r.jobCreated -and $r.jobRemoved) { ' The one-time job was removed.' } elseif ($r.jobCreated) { ' THE ONE-TIME JOB IS STILL THERE (see above).' } else { ' No job was created.' }
    $done = if ("$($r.status)" -eq 'Succeeded' -and -not ($r.result -and -not [bool]$r.result.ok)) { ' The database user is in place (the job read it back); what failed is above.' } else { '' }
    Write-Host "RESULT: FAIL.$done$tail" -ForegroundColor Red
} elseif ($mode -eq 'grant' -and $r.jobKept) {
    $what = switch ("$($r.result.state)") {
        'read-only'    { "the level given is read-only (asked '$($r.result.requested)', consented '$($r.result.consented)') -- nothing was added" }
        'pre-existing' { "the Support app's database user already held db_owner before -- recorded until $($r.result.untilUtc) (UTC) and NOT taken away then" }
        default        { "the Support app's database user in db_owner until $($r.result.untilUtc) (UTC) (asked '$($r.result.requested)', consented '$($r.result.consented)'), read back by the job; the job takes db_owner back then by itself and the read-only access stays" }
    }
    Write-Host "RESULT: PASS$(if (@($r.warnings).Count) { " with $(@($r.warnings).Count) warning(s)" }) -- $what. No firewall rule and no network path was opened." -ForegroundColor Green
} elseif ($mode -in @('install', 'close')) {
    $what = if ($mode -eq 'install') { "the time-limited support access is installed (consent '$($r.result.consented)'), read back by the job" } else { "$($r.result.closed) open time-limited support access grant(s) closed, $($r.result.sessionsEnded) session(s) ended; the read-only access stays" }
    Write-Host "RESULT: PASS$(if (@($r.warnings).Count) { " with $(@($r.warnings).Count) warning(s)" }) -- $what. The one-time job was removed; no firewall rule and no network path was opened." -ForegroundColor Green
} else {
    $what = if ($r.result) { "database user [$($r.result.userName)] in pim_support_read, read-only ($(switch ("$($r.result.state)") { 'created' { 'created' } 'in-place' { 'was already there' } default { 'in place' } }); consent '$($r.result.consented)'), read back by the job" }
            else { 'the job ended Succeeded, which it does only after reading the user and its role back' }
    Write-Host "RESULT: PASS$(if (@($r.warnings).Count) { " with $(@($r.warnings).Count) warning(s)" }) -- $what. The one-time job was removed; no firewall rule and no network path was opened." -ForegroundColor Green
    Write-Host '  The customer ends this access by switching the Invardia Support app off in Microsoft Entra ID (or Grant-PimSupportAccess.ps1 -Remove).' -ForegroundColor DarkGray
}
$script:ssjRc = [int]$r.exit
if ($r.whatIf -and -not @($r.problems).Count) { $script:ssjRc = 0 }
} finally { Stop-PimScriptRun -Script 'Invoke-PimSupportSqlAccessJob' }
exit $script:ssjRc