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


<#
.SYNOPSIS
  Put the SMTP relay password of a PIM Manager environment into its Key Vault, and let the environment's managed
  identities read that one secret. -WhatIf shows every change first and asks for no password.

.DESCRIPTION
  Owner 2026-10-08: "remember i need to have 2 options: shared mailbox or smtp relay solution" / "we dont use certificates
  here, either interactive login or secret". In SMTP relay mode PIM Manager sends through System.Net.Mail with a user name
  and a password. 🔒 The password is NEVER in SQL, in the page or in a log: it is a secret in the environment's own Key
  Vault, read at send time by the environment's managed identities. PIM Manager's Settings > Mail & alerting writes it
  itself when its identity may; otherwise this script does, as a person who may (or as the Invardia Support app):

    1. finds the vault in -SubscriptionId (or, with -CreateVault + -ResourceGroup, creates it: Azure RBAC authorisation);
    2. writes the secret (-SecretName, default PIM-SmtpRelayPassword) -- when Key Vault refuses the writer, it grants the
       writer 'Key Vault Secrets Officer' on THAT VAULT once and retries (the RBAC change can take a few minutes);
    3. grants every -ManagedIdentityObjectId (the Manager's and the engine job's) 'Key Vault Secrets User' on THAT SECRET
       only -- never the whole vault;
    4. reads the secret back and compares it (the value is never printed).

  Sign-in: in the BROWSER by default (Edge, auth code + PKCE, no device code, no module), or the Invardia Support app
  (-AdminAppId + -AdminSecret). No certificate. The password comes from -Password (a SecureString) or a prompt (typed
  twice) -- never as plain text on the command line. -WhatIf signs in, reads and prints every change it would make
  ("What if: ..."), asks for no password and writes nothing (no secret, no role assignment, no vault, no -OutFile).
  Published standalone at https://invardia.com/support/pim/Set-PimSmtpRelayPassword.ps1 (Build-PimSupportScripts.ps1).

.EXAMPLE
  .\Set-PimSmtpRelayPassword.ps1 -TenantId <tenant id> -SubscriptionId <subscription id> -VaultName <vault> `
      -ManagedIdentityObjectId <manager identity object id>,<engine job identity object id> -WhatIf
  Preview; then the same command without -WhatIf (it asks for the password twice).

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
    Role: Key Vault Secrets Officer and User Access Administrator (or Owner) on the environment's Key Vault; Reader on the
          subscription; Contributor on the resource group only with -CreateVault (Azure).
    Hosts: login.microsoftonline.com, management.azure.com, *.vault.azure.net

    PERMISSIONS AND CHANGES (from Set-PimSmtpRelayPassword.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Set-PimSmtpRelayPassword/)
    The person running it needs:
      - Key Vault Secrets Officer [azureRbac, the environment's Key Vault] -- Writes the secret. When you can manage the vault's access (User Access Administrator or Owner) but not its secrets, the script grants you this role on that one vault and retries.
      - User Access Administrator [azureRbac, the environment's Key Vault (Owner or Role Based Access Control Administrator work too)] -- Gives each sending identity read access on the one secret, and, when needed, gives you Key Vault Secrets Officer on the vault.
      - Reader [azureRbac, the subscription (-SubscriptionId)] -- Finds the vault by name in the subscription.
      - Contributor [azureRbac, the resource group (-ResourceGroup), only with -CreateVault] -- Creates the Key Vault when it does not exist.
      - browser sign-in to Azure (first-party public client 'Microsoft Azure PowerShell'), or the Invardia Support app (-AdminAppId + -AdminSecret) [other, Azure Resource Manager and Key Vault in your tenant] -- No PowerShell module and no certificate. The Support app's secret is accepted only for Invardia support; a person signs in in the browser.
    What it creates, changes or grants:
      - create Key Vault -VaultName (Azure RBAC authorisation, standard SKU, soft delete 90 days, the resource group's region) -- only with -CreateVault and only when it does not exist (Azure Resource Manager) @ the resource group -ResourceGroup -- The relay password must live in the environment's own vault, never in SQL, the page or a log. Undo: Delete the Key Vault (it stays soft-deleted for 90 days; purge it to remove it at once).
      - create secret -SecretName (default PIM-SmtpRelayPassword) holding the SMTP relay password, content type 'PIM Manager SMTP relay password'; a new version when it exists. The value is read back to compare and never printed. (Azure Key Vault) @ the Key Vault -VaultName -- PIM Manager reads the password at send time with its managed identities. Undo: Delete the secret (Key Vault > Secrets), or set the previous version back.
      - grant Azure role assignment for the account running the script (Microsoft.Authorization/roleAssignments) -- ONLY when Key Vault refuses the secret write (Azure Resource Manager): Key Vault Secrets Officer @ the Key Vault -VaultName (that vault only) -- Someone who manages the vault's access but not its secrets can then write the secret without a second person. Undo: Key Vault > Access control (IAM) > remove your 'Key Vault Secrets Officer' assignment.
      - grant Azure role assignment for each -ManagedIdentityObjectId (the Manager's and the engine job's identities), with a fixed name so a re-run does not create a second one (Azure Resource Manager): Key Vault Secrets User @ the one secret only (<vault>/secrets/<secret name>), never the whole vault -- The sending identities must read the password at send time, and nothing else in the vault. Undo: Key Vault > the secret > Access control (IAM) > remove the assignment.
      - create the result file -OutFile (JSON: vault, secret name, what was created and granted; never the password) -- only when -OutFile is given and not under -WhatIf (Local machine) @ the path you pass -- For automation that reads the outcome. Undo: Delete the file.
    -WhatIf: Signs in, finds the vault, asks for no password, and prints one "What if:" line per change: create the vault (with -CreateVault), write the secret, the Key Vault Secrets Officer grant to you (only if the write would be refused), and Key Vault Secrets User on the secret for each managed identity. Nothing is written, no -OutFile either.
    Undo: Remove the 'Key Vault Secrets User' assignments on the secret and any 'Key Vault Secrets Officer' assignment the script gave you on the vault, delete the secret, and delete the vault if the script created it.

.LINK
    https://invardia.com/docs/pim/scripts/Set-PimSmtpRelayPassword/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][string]$TenantId,
    [Parameter(Mandatory)][string]$SubscriptionId,
    [Parameter(Mandatory)][string]$VaultName,
    [string]$SecretName = 'PIM-SmtpRelayPassword',
    [string[]]$ManagedIdentityObjectId = @(),
    [System.Security.SecureString]$Password,
    # Create the vault when it does not exist (Azure RBAC authorisation, standard SKU, the resource group's region).
    [switch]$CreateVault,
    [string]$ResourceGroup,
    [string]$AdminAppId,
    [string]$AdminSecret,
    [string]$OutFile
)
$ErrorActionPreference = 'Stop'
# ===== BEGIN inlined helper: _PimMailSetup.ps1 =====
# _PimMailSetup.ps1 -- the pieces behind Initialize-PimMailSender.ps1 and Set-PimSmtpRelayPassword.ps1: which way the
# script signs in, the BROWSER sign-in itself, and a per-API token cache. Dot-source it; it defines functions only (no
# side effects on load).
#
# MAIL-1 (framework DOCS/REQUIREMENTS.md 12.3, owner 2026-10-08): "we dont use certificates here, either interactive login
# or secret. not certificates". So the published scripts sign in in the BROWSER (an Exchange or Global Administrator) or
# with the Invardia Support app's secret; a certificate stays accepted for old callers and is never what a page prints.
#
# NO MODULES (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): plain Invoke-RestMethod + .NET.
# Sign-in is auth code + PKCE on a localhost loopback, Microsoft Edge launched explicitly (the default browser when Edge
# is missing) -- the pattern of _PimEnginePermissions.ps1 (Get-PimEpInteractiveToken), DUPLICATED here on purpose: each
# published script is ONE standalone file (tools/setup/Build-PimSupportScripts.ps1 inlines this), and isolation beats
# DRY between two scripts that ship separately. Never device code.
#
# The public clients (first-party, present in every tenant, no app registration needed):
#   * Exchange Online admin API -- "Microsoft Exchange REST API Based Powershell", the client the ExchangeOnlineManagement
#     V3 module itself signs in with; the token is for https://outlook.office365.com and drives the same
#     /adminapi/beta/<tenant>/InvokeCommand endpoint the module calls.
#   * Microsoft Graph -- "Microsoft Graph Command Line Tools" (as Grant-PimEnginePermissions.ps1).
#   * Azure Resource Manager, Azure SQL, Key Vault -- "Microsoft Azure PowerShell"; one sign-in, the other two from its
#     refresh token (the client is pre-authorised for all three).

# ---- constants --------------------------------------------------------------------------------------------------------
function Get-PimMsExchangeClientId { 'fb78d390-0c51-40cd-8e17-fdbfab77341b' }        # Microsoft Exchange REST API Based Powershell
function Get-PimMsGraphCliClientId { '14d82eec-204b-4c2f-b7e8-296a70dab67e' }        # Microsoft Graph Command Line Tools
function Get-PimMsAzurePowerShellClientId { '1950a258-227b-4e31-a9cf-717495945fc2' } # Microsoft Azure PowerShell
# The delegated Graph rights the shared-mailbox setup reads / changes with: the Exchange plan (subscribedSkus) and the
# initial domain (organization), the service principals (managed identities, Graph), the mailbox's directory user, and
# the removal of a tenant-wide Mail.Send consent (the scope rule of MAIL-1).
function Get-PimMsGraphScopes { @('Organization.Read.All', 'Application.Read.All', 'AppRoleAssignment.ReadWrite.All', 'User.Read.All') }

# ---- which way to sign in (PURE) ----------------------------------------------------------------------------------------
function Resolve-PimMailSetupAuthMode {
    <#
      Decide how the setup script authenticates, BEFORE anything is touched. Returns @{ mode; reason } where mode is
      'browser' | 'secret' | 'certificate' | 'signedIn' and a non-empty reason is a refusal:
        * nothing passed                       -> 'browser' (the person signs in; -AdminAppId is not needed)
        * -AdminSecret (+ -AdminAppId)         -> 'secret'  (the Invardia Support app)
        * -AdminCertThumbprint (+ -AdminAppId) -> 'certificate' (back-compat; never printed)
        * -UseSignedInAccount                  -> 'signedIn' (the Invardia Support session, else the browser)
      Refused: both a secret and a certificate; -UseSignedInAccount with a credential; a credential without -AdminAppId;
      -AdminAppId without a credential (ambiguous: was a secret forgotten?).
    #>
    param([string]$AdminAppId, [string]$AdminSecret, [string]$AdminCertThumbprint, [switch]$UseSignedInAccount)
    $app = "$AdminAppId".Trim(); $sec = "$AdminSecret".Trim(); $cert = "$AdminCertThumbprint".Trim()
    if ($sec -and $cert) { return @{ mode = ''; reason = 'pass EITHER -AdminSecret OR -AdminCertThumbprint, not both.' } }
    if ($UseSignedInAccount) {
        if ($sec -or $cert) { return @{ mode = ''; reason = '-UseSignedInAccount takes no -AdminSecret / -AdminCertThumbprint.' } }
        return @{ mode = 'signedIn'; reason = '' }
    }
    if ($sec -or $cert) {
        if (-not $app) { return @{ mode = ''; reason = '-AdminAppId is required with -AdminSecret / -AdminCertThumbprint (the app the credential belongs to).' } }
        return @{ mode = $(if ($sec) { 'secret' } else { 'certificate' }); reason = '' }
    }
    if ($app) { return @{ mode = ''; reason = "-AdminAppId $app was passed without its credential: add -AdminSecret (the Invardia Support app's secret), or leave -AdminAppId out to sign in in the browser." } }
    return @{ mode = 'browser'; reason = '' }
}

function Test-PimMsInteractiveHost {
    # A browser sign-in needs a person at this console. An unattended run (a deploy step, a scheduled task, a redirected
    # stdin) must be REFUSED instead -- it would otherwise open a browser nobody sees and wait five minutes.
    try { if (-not [Environment]::UserInteractive) { return $false } } catch { }
    try { if ([Console]::IsInputRedirected) { return $false } } catch { }
    return $true
}

function Get-PimMsExoAnchor {
    # X-AnchorMailbox for the Exchange admin API: the signed-in person's own UPN with a delegated token, the system
    # mailbox of the initial domain with an app-only one (what the EXO V3 module sends in each case).
    param([string]$Mode, [string]$Upn, [string]$InitialDomain)
    if ($Mode -eq 'browser' -and "$Upn".Trim()) { return "UPN:$("$Upn".Trim())" }
    return "UPN:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@$("$InitialDomain".Trim())"
}

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

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

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

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

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

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

function Get-PimMsSignInFailureHint {
    # PURE: one sentence for a sign-in error the person can act on ('' when there is nothing specific to say).
    param([string]$ErrorText)
    $e = "$ErrorText"
    if ($e -match 'AADSTS50011|redirect') { return 'This tenant refuses the local sign-in answer address for this Microsoft client. Run the script with the Invardia Support app instead: -AdminAppId <support app id> -AdminSecret <its secret>.' }
    if ($e -match 'AADSTS65001|consent') { return 'The sign-in needs an administrator''s consent: sign in as a Global Administrator once, or run with the Invardia Support app (-AdminAppId + -AdminSecret).' }
    if ($e -match 'AADSTS50105|AADSTS50020|not assigned|does not exist in tenant') { return 'Sign in with an account of THIS tenant (an Exchange Administrator or Global Administrator).' }
    return ''
}

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

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

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

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

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

# A token for another resource (or a fresh one) from a refresh token of the same public client -- no second browser tab.
function Get-PimMsRefreshedToken {
    param([Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$RefreshToken, [Parameter(Mandatory)][string[]]$Scopes, [string]$Tenant = 'organizations')
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $ClientId; grant_type = 'refresh_token'; refresh_token = $RefreshToken; scope = (Get-PimMsScopeString -Scopes $Scopes)
    }
}

# ---- the per-API token cache -------------------------------------------------------------------------------------------
function Get-PimMsBrowserApi {
    <#
      PURE: which public client + scopes serve a resource, and which sign-in it shares.
      Returns @{ api; clientId; scopes; family } -- family is the refresh-token group: 'azure' covers ARM, SQL and Key
      Vault (one sign-in), 'graph' and 'exchange' have their own.
    #>
    param([Parameter(Mandatory)][string]$Resource)
    $r = "$Resource".Trim().TrimEnd('/').ToLowerInvariant()
    switch -regex ($r) {
        '^(graph|https://graph\.microsoft\.com)$'          { return @{ api = 'graph'; clientId = (Get-PimMsGraphCliClientId); scopes = @(Get-PimMsGraphScopes); family = 'graph' } }
        '^(exchange|https://outlook\.office365\.com)$'     { return @{ api = 'exchange'; clientId = (Get-PimMsExchangeClientId); scopes = @('https://outlook.office365.com/.default'); family = 'exchange' } }
        '^(arm|https://management\.azure\.com)$'           { return @{ api = 'arm'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://management.azure.com/.default'); family = 'azure' } }
        '^(sql|https://database\.windows\.net)$'           { return @{ api = 'sql'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://database.windows.net/.default'); family = 'azure' } }
        '^(keyvault|https://vault\.azure\.net)$'           { return @{ api = 'keyvault'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://vault.azure.net/.default'); family = 'azure' } }
    }
    throw "no browser sign-in is defined for '$Resource'"
}

function Get-PimMsBrowserToken {
    <#
      An access token for -Resource as the person who signed in, cached per API for the run. The first call of a family
      opens the browser (the next ones carry the first sign-in's account as the login hint, so the browser does not ask
      again); a family's other APIs and an expiring token are served from its refresh token.
      Test seam: $script:PimMsAcquire = { param($ClientId, $Scopes, $Tenant, $LoginHint, $RefreshToken) <token response> }.
    #>
    param([Parameter(Mandatory)][string]$Resource, [Parameter(Mandatory)][string]$TenantId)
    if (-not $script:PimMsTokens) { $script:PimMsTokens = @{} }
    if (-not $script:PimMsRefresh) { $script:PimMsRefresh = @{} }
    $spec = Get-PimMsBrowserApi -Resource $Resource
    $now = (Get-Date).ToUniversalTime()
    $hit = $script:PimMsTokens[$spec.api]
    if ($hit -and $hit.expires -gt $now.AddMinutes(5)) { return $hit.token }
    $acquire = $script:PimMsAcquire
    $rt = $script:PimMsRefresh[$spec.family]
    $resp = $null
    if ($rt) {
        try {
            $resp = if ($acquire) { & $acquire $spec.clientId $spec.scopes $TenantId $script:PimMsLoginHint $rt }
                    else { Get-PimMsRefreshedToken -ClientId $spec.clientId -RefreshToken $rt -Scopes $spec.scopes -Tenant $TenantId }
        } catch { $resp = $null }
    }
    if (-not $resp) {
        if (-not $acquire -and -not (Test-PimMsInteractiveHost)) { throw 'a browser sign-in needs a person at this console, and this session is not interactive -- run the command in a PowerShell window, or pass -AdminAppId + -AdminSecret (the Invardia Support app).' }
        $what = switch ($spec.family) { 'graph' { 'Microsoft Graph' } 'exchange' { 'Exchange Online' } default { 'Azure' } }
        $resp = if ($acquire) { & $acquire $spec.clientId $spec.scopes $TenantId $script:PimMsLoginHint $null }
                else { Get-PimMsInteractiveToken -ClientId $spec.clientId -Scopes $spec.scopes -Tenant $TenantId -LoginHint $script:PimMsLoginHint -What $what }
    }
    $tok = "$($resp.access_token)"
    if (-not $tok) { throw "the sign-in returned no access token for $($spec.api)" }
    $claims = ConvertFrom-PimMsJwtClaims -Token $tok
    if ($claims -and "$($claims.tid)".Trim() -and "$($claims.tid)".Trim() -ine "$TenantId".Trim()) {
        throw "you signed in to tenant $($claims.tid), not $TenantId -- sign in with an account of the tenant this environment runs in."
    }
    if ($claims -and -not $script:PimMsLoginHint) {
        $u = "$(if ($claims.upn) { $claims.upn } elseif ($claims.preferred_username) { $claims.preferred_username } else { $claims.unique_name })".Trim()
        if ($u) { $script:PimMsLoginHint = $u }
    }
    if ("$($resp.refresh_token)".Trim()) { $script:PimMsRefresh[$spec.family] = "$($resp.refresh_token)" }
    $secs = 3000; try { if ([int]$resp.expires_in -gt 0) { $secs = [int]$resp.expires_in } } catch { }
    $script:PimMsTokens[$spec.api] = @{ token = $tok; expires = $now.AddSeconds($secs) }
    return $tok
}

function Get-PimMsSignedInUpn {
    # The person who signed in (the first token's upn), '' before any sign-in.
    "$($script:PimMsLoginHint)".Trim()
}

function Get-PimMsAppToken {
    # An app-only token for -Resource as the Invardia Support app (client credentials, its secret). No module.
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$ClientSecret, [Parameter(Mandatory)][string]$Resource)
    $spec = Get-PimMsBrowserApi -Resource $Resource
    $scope = (@($spec.scopes) | Where-Object { $_ -match '^https://' } | Select-Object -First 1)
    if (-not $scope) { $scope = 'https://graph.microsoft.com/.default' }
    $scope = ($scope -replace '/[^/]+$', '/.default')
    (Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $ClientId; client_secret = $ClientSecret; grant_type = 'client_credentials'; scope = $scope }).access_token
}

# ---- the SMTP relay password in Key Vault (PURE pieces; Set-PimSmtpRelayPassword.ps1 does the calls) -------------------
function Get-PimKvRoleId {
    # Built-in Azure roles by name (the ids are the same in every tenant).
    param([Parameter(Mandatory)][ValidateSet('SecretsUser', 'SecretsOfficer')][string]$Role)
    switch ($Role) { 'SecretsUser' { '4633458b-17de-408a-b874-0445c86b69e6' } 'SecretsOfficer' { 'b86a8fe4-44ce-4948-aee5-eccb2c155cd7' } }
}

function Select-PimKvVault {
    # PURE: the ONE vault called -Name in a subscription's vault list (ARM value[]), or @{ vault = $null; reason }.
    param([object[]]$Vaults = @(), [Parameter(Mandatory)][string]$Name)
    $hits = @(@($Vaults) | Where-Object { $_ -and "$($_.name)" -ieq "$Name".Trim() })
    if ($hits.Count -eq 1) { return @{ vault = $hits[0]; reason = '' } }
    if ($hits.Count -gt 1) { return @{ vault = $null; reason = "more than one Key Vault is called $Name -- refusing to pick one" } }
    return @{ vault = $null; reason = "no Key Vault called $Name in this subscription" }
}

function Get-PimKvSecretScope {
    # PURE: the Azure RBAC scope of ONE secret -- the read right is granted on the secret, never on the whole vault.
    param([Parameter(Mandatory)][string]$VaultId, [Parameter(Mandatory)][string]$SecretName)
    "$("$VaultId".TrimEnd('/'))/secrets/$SecretName"
}

function New-PimKvRoleAssignmentRequest {
    # PURE: the ARM PUT of one role assignment (deterministic name per scope + principal + role, so a re-run is the same
    # request and ARM answers "already exists" instead of creating a second one).
    param([Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$RoleId,
          [Parameter(Mandatory)][string]$PrincipalId, [ValidateSet('ServicePrincipal', 'User', 'Group')][string]$PrincipalType = 'ServicePrincipal')
    $md5 = [Security.Cryptography.MD5]::Create()
    $bytes = $md5.ComputeHash([Text.Encoding]::UTF8.GetBytes(("{0}|{1}|{2}" -f $Scope.ToLowerInvariant(), $PrincipalId.ToLowerInvariant(), $RoleId.ToLowerInvariant())))
    $name = ([guid]::new($bytes)).ToString()
    @{
        path = "$Scope/providers/Microsoft.Authorization/roleAssignments/$name`?api-version=2022-04-01"
        body = @{ properties = @{ roleDefinitionId = "/subscriptions/$SubscriptionId/providers/Microsoft.Authorization/roleDefinitions/$RoleId"; principalId = $PrincipalId; principalType = $PrincipalType } }
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# ===== END inlined helper: _PimScriptDoc.ps1 =====
$null = Start-PimScriptRun -Script 'Set-PimSmtpRelayPassword'
try {

$authPlan = Resolve-PimMailSetupAuthMode -AdminAppId $AdminAppId -AdminSecret $AdminSecret
if ($authPlan.reason) { throw "Set-PimSmtpRelayPassword: $($authPlan.reason)" }
if ($authPlan.mode -notin @('browser', 'secret')) { throw 'Set-PimSmtpRelayPassword: sign in in the browser (no credential) or pass -AdminAppId + -AdminSecret.' }
if ($authPlan.mode -eq 'browser' -and -not (Test-PimMsInteractiveHost)) { throw 'Set-PimSmtpRelayPassword: this run signs in in the BROWSER, and this session is not interactive -- run it in a PowerShell window, or pass -AdminAppId + -AdminSecret.' }
if ($SecretName -notmatch '^[0-9A-Za-z-]{1,127}$') { throw "Set-PimSmtpRelayPassword: not a Key Vault secret name: $SecretName" }
if ($VaultName -notmatch '^[A-Za-z][A-Za-z0-9-]{1,22}[A-Za-z0-9]$') { throw "Set-PimSmtpRelayPassword: not a Key Vault name: $VaultName" }
$miIds = @(@($ManagedIdentityObjectId) | ForEach-Object { "$_" -split '[,;\s]+' } | ForEach-Object { $_.Trim() } | Where-Object { $_ })
foreach ($m in $miIds) { if ($m -notmatch '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') { throw "Set-PimSmtpRelayPassword: -ManagedIdentityObjectId '$m' is not an object id" } }

$result = [ordered]@{ ok = $false; vault = $VaultName; secretName = $SecretName; vaultCreated = $false; secretWritten = $false; readBack = $false; grants = @(); reason = '' }
function Note($m, $c = 'Gray') { Write-Host "    $m" -ForegroundColor $c }
function Step($m) { Write-Host "`n--- $m ---" -ForegroundColor Cyan }
function Done {
    if (-not "$OutFile".Trim()) { return }
    if ($WhatIfPreference) { Write-Host "What if: would write the result to $OutFile (not written under -WhatIf)"; return }
    try { ($result | ConvertTo-Json -Depth 6) | Set-Content -LiteralPath $OutFile -Encoding utf8 } catch { Write-Warning "could not write -OutFile: $($_.Exception.Message)" }
}
function Fail($why) { $result.reason = $why; Done; Write-Host "`nRESULT: FAILED -- $why" -ForegroundColor Red; exit 1 }

function Get-Tok([string]$Resource) {
    # The sign-in is a READ the -WhatIf preview needs: an inherited -WhatIf would stop Start-Process from opening the
    # browser (the run would then wait 5 minutes for nothing). Local to this function only.
    $WhatIfPreference = $false
    if ($authPlan.mode -eq 'secret') { return (Get-PimMsAppToken -TenantId $TenantId -ClientId $AdminAppId -ClientSecret $AdminSecret -Resource $Resource) }
    return (Get-PimMsBrowserToken -Resource $Resource -TenantId $TenantId)
}
function Arm([string]$Method = 'GET', [string]$Path, $Body) {
    $a = @{ Method = $Method; Uri = "https://management.azure.com$Path"; Headers = @{ Authorization = "Bearer $(Get-Tok 'arm')"; 'Content-Type' = 'application/json' } }
    if ($null -ne $Body) { $a.Body = ($Body | ConvertTo-Json -Depth 10) }
    Invoke-RestMethod @a
}
function Kv([string]$Method = 'GET', [string]$Name, $Body) {
    $a = @{ Method = $Method; Uri = "https://$VaultName.vault.azure.net/secrets/$Name`?api-version=7.4"; Headers = @{ Authorization = "Bearer $(Get-Tok 'keyvault')"; 'Content-Type' = 'application/json' } }
    if ($null -ne $Body) { $a.Body = ($Body | ConvertTo-Json -Depth 4) }
    Invoke-RestMethod @a
}
function ErrText($e) { ("$($e.Exception.Message) $($e.ErrorDetails.Message)" -replace '\s+', ' ').Trim() }

Write-Host ('=' * 78) -ForegroundColor Cyan
Write-Host " PIM MANAGER -- SMTP RELAY PASSWORD -> Key Vault $VaultName / $SecretName" -ForegroundColor Cyan
Write-Host ('=' * 78) -ForegroundColor Cyan

# --- the password, before anything is touched (not under -WhatIf: a preview needs no secret) -----------------------------
if ($WhatIfPreference) { Note 'WhatIf: the password is not asked for -- it is asked (twice) when you run without -WhatIf.' 'DarkYellow' }
elseif (-not $Password) {
    $p1 = Read-Host -AsSecureString 'SMTP relay password'
    $p2 = Read-Host -AsSecureString 'Type it again'
    $b1 = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($p1); $b2 = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($p2)
    try { $same = ([Runtime.InteropServices.Marshal]::PtrToStringBSTR($b1) -ceq [Runtime.InteropServices.Marshal]::PtrToStringBSTR($b2)) }
    finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($b1); [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($b2) }
    if (-not $same) { Fail 'the two passwords differ -- nothing was changed' }
    $Password = $p1
}
if (-not $WhatIfPreference -and $Password.Length -lt 1) { Fail 'the password is empty -- nothing was changed' }

# --- 1. the vault --------------------------------------------------------------------------------------------------------
Step "[1] Key Vault $VaultName in subscription $SubscriptionId"
try { $list = @((Arm -Path "/subscriptions/$SubscriptionId/providers/Microsoft.KeyVault/vaults?api-version=2023-07-01").value) }
catch { Fail "could not list the Key Vaults of subscription $SubscriptionId : $(ErrText $_)" }
$pick = Select-PimKvVault -Vaults $list -Name $VaultName
$vault = $pick.vault
if (-not $vault) {
    if (-not $CreateVault) { Fail "$($pick.reason). Pass -CreateVault -ResourceGroup <resource group> to create it, or name the environment's vault." }
    if (-not "$ResourceGroup".Trim()) { Fail '-CreateVault needs -ResourceGroup (where the vault is created).' }
    try { $rg = Arm -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup`?api-version=2021-04-01" } catch { Fail "resource group $ResourceGroup not found: $(ErrText $_)" }
    if ($PSCmdlet.ShouldProcess($VaultName, "create Key Vault in $ResourceGroup ($($rg.location))")) {
        # SEC-03 (Invardia 2026-11-07): purge protection like every PIM vault; a PRIVATE install's updater gives it the private shape on its next run (rule 11, step 2g-bis)
        $body = @{ location = "$($rg.location)"; properties = @{ tenantId = $TenantId; sku = @{ family = 'A'; name = 'standard' }; enableRbacAuthorization = $true; enableSoftDelete = $true; softDeleteRetentionInDays = 90; enablePurgeProtection = $true } }
        try { [void](Arm -Method PUT -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.KeyVault/vaults/$VaultName`?api-version=2023-07-01" -Body $body) }
        catch { Fail "could not create Key Vault $VaultName : $(ErrText $_)" }
        $deadline = (Get-Date).AddMinutes(3)
        do { Start-Sleep -Seconds 10; try { $vault = Arm -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.KeyVault/vaults/$VaultName`?api-version=2023-07-01" } catch { $vault = $null } } while (-not $vault -and (Get-Date) -lt $deadline)
        if (-not $vault) { Fail "Key Vault $VaultName was created but is not readable yet -- re-run in a few minutes" }
        $result.vaultCreated = $true
        Note "created (Azure RBAC authorisation): $($vault.id)" 'Green'
    } else {
        # -WhatIf: the vault does not exist yet; the next steps are previewed against the id it WOULD get.
        $vault = [pscustomobject]@{ id = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.KeyVault/vaults/$VaultName"; properties = [pscustomobject]@{ enableRbacAuthorization = $true } }
    }
} else { Note "found: $($vault.id)" 'DarkGray' }
if ($vault.properties -and -not $vault.properties.enableRbacAuthorization) { Note 'this vault uses ACCESS POLICIES, not Azure RBAC: the read grants below do not apply -- give the managed identities "Get" on secrets in its access policies.' 'Yellow' }

if ($WhatIfPreference) {
    # PowerShell's own "What if:" line for every change the run would make (ShouldProcess answers $false under -WhatIf).
    [void]$PSCmdlet.ShouldProcess("Key Vault $VaultName, secret $SecretName", 'write the SMTP relay password (Key Vault data plane; the value is never printed)')
    [void]$PSCmdlet.ShouldProcess("Key Vault $VaultName ($($vault.id))", "ONLY IF Key Vault refuses the write: assign Azure role 'Key Vault Secrets Officer' on this vault to the signed-in account")
    $secScope = Get-PimKvSecretScope -VaultId "$($vault.id)" -SecretName $SecretName
    foreach ($oid in $miIds) { [void]$PSCmdlet.ShouldProcess("managed identity $oid", "assign Azure role 'Key Vault Secrets User' on the secret only ($secScope)") }
    if (-not $miIds.Count) { Note 'WhatIf: no -ManagedIdentityObjectId given -- nobody would be granted read access.' 'Yellow' }
    $result.ok = $true; Done; exit 0
}

# --- 2. the secret -------------------------------------------------------------------------------------------------------
Step "[2] write secret $SecretName"
$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($Password)
try {
    $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
    $writeBody = @{ value = $plain; contentType = 'PIM Manager SMTP relay password' }
    $written = $false; $granted = $false
    $deadline = (Get-Date).AddMinutes(6)
    while (-not $written) {
        try { [void](Kv -Method PUT -Name $SecretName -Body $writeBody); $written = $true }
        catch {
            $t = (ErrText $_).Replace($plain, '***')
            if ($t -notmatch '(?i)\b403\b|Forbidden') { Fail "Key Vault refused the write: $t" }
            if (-not $granted) {
                # the writer may manage the vault (Owner / User Access Administrator) but not its secrets: grant the data-plane
                # right on THIS vault to the writer itself, once
                $claims = ConvertFrom-PimMsJwtClaims -Token (Get-Tok 'keyvault')
                $me = "$($claims.oid)"; $kind = if ("$($claims.idtyp)" -eq 'app' -or -not "$($claims.upn)$($claims.preferred_username)") { 'ServicePrincipal' } else { 'User' }
                if (-not $me) { Fail "Key Vault refused the write and the signed-in identity could not be read: $t" }
                $req = New-PimKvRoleAssignmentRequest -Scope "$($vault.id)" -SubscriptionId $SubscriptionId -RoleId (Get-PimKvRoleId -Role SecretsOfficer) -PrincipalId $me -PrincipalType $kind
                try { [void](Arm -Method PUT -Path $req.path -Body $req.body); Note "granted 'Key Vault Secrets Officer' on $VaultName to the writer ($me) -- waiting for it to take effect" 'Yellow' }
                catch { $g = ErrText $_; if ($g -notmatch 'RoleAssignmentExists') { Fail "Key Vault refused the write ($t), and the writer could not be given 'Key Vault Secrets Officer' on the vault: $g" } }
                $granted = $true
            }
            if ((Get-Date) -ge $deadline) { Fail 'Key Vault still refuses the write 6 minutes after the grant -- re-run the script; the grant is in place' }
            Start-Sleep -Seconds 20
        }
    }
    $result.secretWritten = $true
    Note 'written' 'Green'
    # --- 4. read back (moved up: the value is still in memory here, and is compared, never printed) ---------------------
    $back = $null
    try { $back = "$((Kv -Name $SecretName).value)" } catch { $back = $null }
    $result.readBack = ($null -ne $back -and $back -ceq $plain)
    if (-not $result.readBack) { Note 'the secret could not be read back to compare (the writer may hold write-only rights) -- it was written' 'Yellow' }
    else { Note 'read back and identical' 'Green' }
} finally {
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr); $plain = $null; $writeBody = $null; $back = $null
}

# --- 3. who may read it --------------------------------------------------------------------------------------------------
Step "[3] 'Key Vault Secrets User' on $SecretName (the secret only) for the sending identities"
if (-not $miIds.Count) { Note 'no -ManagedIdentityObjectId given: nobody was granted read access -- PIM Manager cannot send until its identities may read the secret.' 'Yellow' }
$scope = Get-PimKvSecretScope -VaultId "$($vault.id)" -SecretName $SecretName
foreach ($oid in $miIds) {
    $req = New-PimKvRoleAssignmentRequest -Scope $scope -SubscriptionId $SubscriptionId -RoleId (Get-PimKvRoleId -Role SecretsUser) -PrincipalId $oid
    try { [void](Arm -Method PUT -Path $req.path -Body $req.body); $result.grants += [ordered]@{ principalId = $oid; state = 'granted' }; Note "granted to $oid" 'Green' }
    catch {
        $g = ErrText $_
        if ($g -match 'RoleAssignmentExists') { $result.grants += [ordered]@{ principalId = $oid; state = 'already' }; Note "already held by $oid" 'DarkGray' }
        else { $result.grants += [ordered]@{ principalId = $oid; state = 'FAILED'; reason = $g }; Fail "could not grant read access on the secret to $oid : $g" }
    }
}

$result.ok = $true
Done
Write-Host ''
Write-Host ('=' * 78) -ForegroundColor Cyan
Write-Host ' SMTP RELAY PASSWORD READY' -ForegroundColor Green
Write-Host ('=' * 78) -ForegroundColor Cyan
Write-Host "  vault / secret : $VaultName / $SecretName (the value was not printed)"
Write-Host "  read by        : $(if ($miIds.Count) { $miIds -join ', ' } else { 'nobody yet' })"
Write-Host '  NEXT           : PIM Manager > Settings > Mail & alerting (or Get Started > Mail sender) > SMTP relay: the same'
Write-Host "                   vault and secret name, then Send a test mail. A new grant can take a few minutes to apply."
exit 0
} finally { Stop-PimScriptRun -Script 'Set-PimSmtpRelayPassword' }