#Requires -Version 5.1
# PIM Manager 3.0.70 -- Deploy-PimActivatorClient.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: ..\setup\_pimscriptdoc.ps1, _pimactivatorauth.ps1, ..\setup\_pimloopbackanswer.ps1, _pimactivatorhybridpolicy.ps1)


<#
.SYNOPSIS
    Installs the PIM Activator browser extension on this machine (Edge, Chrome or both) through local Chromium enterprise policy in the registry -- force-install, install source, extension settings and the tenant catalog -- for servers and machines without Intune; -Uninstall removes only what it wrote.

.DESCRIPTION
    Documentation (purpose, who may run it, every change and permission, -WhatIf, undo):
    https://invardia.com/docs/pim/scripts/Deploy-PimActivatorClient/
    -WhatIf reads the machine's current policies (and signs in only when the tenant catalog is auto-discovered) and
    prints every registry value it would set or remove; it writes nothing.

    The extension itself is downloaded by the BROWSER, not by this script: the forcelist names the update manifest
    (-UpdateUrl) and the browser installs and updates the signed CRX from it (Chromium accepts a CRX only when its
    signing key matches the extension id).

    Designed for unattended Intune / Group Policy / Configuration Manager rollout.

    Writes the Chromium policies that tell the browser to install + auto-update
    the extension from the given -UpdateUrl on next launch
    (ExtensionInstallForcelist, ExtensionInstallSources, ExtensionSettings), plus
    the tenant catalog the popup reads from chrome.storage.managed.

    Per-machine (-Scope Machine, default, HKLM, requires admin) or per-user
    (-Scope User, HKCU, no admin). Both browsers read the SAME key names
    under different roots:
      Edge   : SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist
      Chrome : SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist

    The tenant catalog (tenant id + client id per tenant) goes to
    <policy root>\3rdparty\extensions\<id>\policy\tenantCatalog, which the popup's
    "Use centrally deployed" option reads. Users can instead import a catalog or
    type one tenant in the popup's setup wizard.

    Re-runnable. Safe under SYSTEM. Exit code 0 on success; 1 when the tenant
    catalog was asked for but could not be written (the policies are still written).

.PARAMETER ExtensionId
    32-char Chromium extension id (lowercase a-p). Required.

.PARAMETER UpdateUrl
    The update.xml URL the extension auto-updates from. For the
    PIM4EntraPS-hosted CRX this is
    https://knudsenmorten.github.io/PIM4EntraPS/updates.xml

.PARAMETER Scope
    'Machine' (default, HKLM, requires admin, force-installs for every user
    on the box) or 'User' (HKCU, no admin required, current-user only, no
    Intune conflict).

    On Intune-managed devices the HKLM ExtensionInstallForcelist value will
    be overwritten by Intune's policy on next sync -- use Intune's own
    Edge management service policy instead (see README.md: Prerequisites) and the Intune Remediation in intune-remediation\.

.PARAMETER Browser
    'Edge', 'Chrome', or 'Both' (default).

.PARAMETER Uninstall
    Remove ONLY what this script wrote for this extension id: our forcelist /
    allowlist rows, our install-source row (kept while another forcelist row still
    installs from that host), our ExtensionSettings entry and our 3rdparty policy
    tree. The org's own rows and ExtensionSettings entries are left in place.

.PARAMETER ClientId
    Optional. The PIM Activator app registration's Application (client) id for the
    tenant catalog. When omitted, the app is resolved by EXACT display name
    (-AppDisplayName) and must be unique -- never "the first app whose name starts
    with PIM Activator".

.PARAMETER AppDisplayName
    Exact display name used to find the app registration when -ClientId is not given.
    Default 'PIM Activator' (what Deploy-PimActivatorBackend.ps1 creates).

.PARAMETER TenantId
    With -ClientId: write the tenant catalog from these values (no sign-in, no file).

.PARAMETER AutoActivateMaxGroups
    Per-device cap on auto-activation: 0 = off, N = at most N groups, -1 = remove the cap. Not passed = left alone.
    Written for both PIM Activator extensions (production and test), the same as the Intune Remediation.

.PARAMETER BulkActivateConfirmThreshold
    Per-device "click again to confirm" threshold for bulk activation: 1-100, -1 = remove it. Not passed = left alone.
    Both extensions, as above. A tenant's own bulkActivateConfirmThreshold in the catalog wins over it.

.PARAMETER ActivationEndTime
    Per-device end-of-day time 'HH:MM' (local time): every activation ends no later than this today; one started after it
    gets its normal duration. 'none' = remove it. Not passed = left alone. Both extensions, as above.

.PARAMETER Prefix
    With -TenantId and -ClientId: list only groups whose names start with this text (-EntraPrefix: Entra roles,
    -AzurePrefix: Azure roles). The same settings as the Intune Remediation.

.EXAMPLE
    # Server without Intune, the same settings as the Intune Remediation (the command the PIM Manager page shows):
    .\Deploy-PimActivatorClient.ps1 -Scope Machine -Browser Both -Channel Released -TenantId <tenant id> -ClientId <app id> `
        -TenantName 'Contoso' -AutoActivateMaxGroups 3 -BulkActivateConfirmThreshold 5

.EXAMPLE
    # Preview: every registry value it would set -- writes nothing:
    .\Deploy-PimActivatorClient.ps1 -Scope Machine -Browser Both -TenantId <tenant id> -ClientId <app id> -WhatIf

.EXAMPLE
    # Default per-machine install (HKLM, requires admin, applies to every
    # user on this box):
    .\Deploy-PimActivatorClient.ps1

    # On next Edge / Chrome launch the extension installs for every user.
    # Each user then opens the popup, picks the centrally deployed tenant,
    # signs in, and starts activating PIM eligibilities.

.EXAMPLE
    # Current-user install (HKCU, no admin needed, won't conflict with
    # Intune-pushed policy):
    .\Deploy-PimActivatorClient.ps1 -Scope User

.EXAMPLE
    # Edge only:
    .\Deploy-PimActivatorClient.ps1 `
        -ExtensionId 'eheocihmlppcophaeakmdenhgcookkab' `
        -UpdateUrl   'https://knudsenmorten.github.io/PIM4EntraPS/updates.xml' `
        -Browser Edge

.EXAMPLE
    # Force the org's activation defaults (justification + duration) for every
    # tenant entry written -- overrides the auto-discover fallback ('Change in
    # infrastructure' / 8h) or any value carried in -CatalogJsonPath:
    .\Deploy-PimActivatorClient.ps1 `
        -DefaultJustification 'Approved change / incident work' `
        -DefaultDurationHours 4

.EXAMPLE
    # Server: cap auto-activation at 3 groups on THIS machine (both extensions), leaving the rest as is.
    # 0 turns auto-activation off; -1 removes the cap again.
    .\Deploy-PimActivatorClient.ps1 -Channel Test -AutoActivateMaxGroups 3

.EXAMPLE
    # Uninstall (removes only OUR policy rows / entries; the extension
    # self-removes on next launch):
    .\Deploy-PimActivatorClient.ps1 `
        -ExtensionId 'eheocihmlppcophaeakmdenhgcookkab' `
        -Uninstall

.EXAMPLE
    # Intune managed-policy equivalent (per-user, no script needed):
    # Microsoft Edge -> Configuration profile -> Settings catalog
    # -> Extensions -> Configure which extensions are installed silently
    # -> Add: eheocihmlppcophaeakmdenhgcookkab;https://knudsenmorten.github.io/PIM4EntraPS/updates.xml

.NOTES
    Requirements:
      PowerShell: Windows PowerShell 5.1 (powershell.exe) or PowerShell 7 on Windows -- one of PIM's three exceptions
                  to PowerShell 7. Why: Group Policy startup scripts and Configuration Manager run it in Windows
                  PowerShell on machines that have no PowerShell 7.
      Role: local Administrator (elevated PowerShell) for -Scope Machine, the default; none for -Scope User. No
            Microsoft Entra role: only the tenant lookup (without -TenantId and -ClientId) signs in, to read the
            organisation and the PIM Activator app.
      Hosts: none when -TenantId and -ClientId are given; otherwise login.microsoftonline.com, graph.microsoft.com.
             The browser, not this script, then fetches the extension from its update address (-UpdateUrl).

    PERMISSIONS AND CHANGES (from Deploy-PimActivatorClient.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Deploy-PimActivatorClient/)
    The person running it needs:
      - Local Administrator (elevated PowerShell) [other, this machine; only for -Scope Machine (HKLM, the default)] -- machine policy lives under HKLM. -Scope User (HKCU, the current user only) needs no elevation.
      - Delegated sign-in: Organization.Read.All, Application.Read.All (read only) [other, Microsoft Graph, for the first-party app Microsoft Graph Command Line Tools] -- ONLY when neither -TenantId + -ClientId nor -CatalogJsonPath is given: the tenant and the PIM Activator app are looked up live. The command PIM Manager shows passes both, so it signs in to nothing.
    What it creates, changes or grants:
      - update <HKLM or HKCU>\SOFTWARE\Policies\Microsoft\Edge and \Google\Chrome \ExtensionInstallForcelist: one row '<extension id>;<update URL>' in the slot already holding our id, else the lowest free slot; other rows carrying our id are removed (this machine's registry) -- the browser installs and keeps the extension updated Undo: Deploy-PimActivatorClient.ps1 -Uninstall (removes only our rows)
      - update ...\ExtensionInstallSources: one row with the update host pattern (https://<host>/*) (this machine's registry) -- allows the install where a hardened baseline restricts install sources Undo: -Uninstall (kept while another forcelist row still installs from that host)
      - update ...\ExtensionSettings: our entry (force_installed, runtime_allowed_hosts) merged into the organisation's dictionary -- their entries are kept (this machine's registry) -- an extension update can never be silently disabled as a permission expansion Undo: -Uninstall (takes only our id out)
      - update ...\ExtensionInstallAllowlist: one row with our id -- only with -WriteAllowlist (this machine's registry) -- for environments that block every extension ('*' blocklist) Undo: -Uninstall
      - create ...\3rdparty\extensions\<extension id>\policy\tenantCatalog (tenant name, tenant id, app client id, activation defaults; plus -AdditionalTenantsJson tenants) (this machine's registry) -- the extension's 'Use centrally deployed' setup reads it Undo: -Uninstall (removes the whole 3rdparty\extensions\<extension id> key)
      - update ...\3rdparty\extensions\<id>\policy\autoActivateMaxGroups (DWORD) for BOTH PIM Activator extensions (production and test) -- only with -AutoActivateMaxGroups (-1 removes it) (this machine's registry) -- per-device cap on auto-activation, the same for production and test (as the Intune Remediation writes it) Undo: re-run with -AutoActivateMaxGroups -1
      - update ...\3rdparty\extensions\<id>\policy\bulkActivateConfirmThreshold (DWORD) for BOTH PIM Activator extensions -- only with -BulkActivateConfirmThreshold (-1 removes it) (this machine's registry) -- per-device 'click again to confirm' threshold for bulk activation (as the Intune Remediation writes it) Undo: re-run with -BulkActivateConfirmThreshold -1
      - remove with -Uninstall: our forcelist / allowlist / install-source rows, our ExtensionSettings entry and the 3rdparty\extensions\<extension id> key -- nothing of the organisation's (this machine's registry) -- removes the PIM Activator from this machine (the browser uninstalls it on its next start) Undo: run the install again
    -WhatIf: Reads this machine's policies and prints every registry value it would set or remove (forcelist slot, install source, ExtensionSettings entry, tenant catalog, per-device limits). Nothing is written. A preview of -Scope Machine runs without elevation.
    Undo: Deploy-PimActivatorClient.ps1 -Uninstall (same -Scope, -Browser and -Channel): removes only this script's rows, entries and keys; the browser removes the extension on its next start.

    Existing policies: the org's own extension policies are never overwritten: our rows go
    into the slot already holding our id, else the lowest free slot, and our
    ExtensionSettings entry is MERGED into the org's dictionary. Same layout and the
    same code (_PimActivatorHybridPolicy.ps1) as Deploy-PimActivatorHybrid.ps1 -Target
    LocalGpo, so the two writers cannot disagree. That file must sit next to this one.
    Tested on Edge for Business 120+ and Chrome 120+. Both browsers pick up
    policy changes on next launch; no reboot required.
    A transcript of the run is written to <temp>\pim-manager-logs\ (its path is printed).

.LINK
    https://invardia.com/docs/pim/scripts/Deploy-PimActivatorClient/
#>
[CmdletBinding(DefaultParameterSetName = 'Install', SupportsShouldProcess)]
param(
    # Extension id is constant across every install of this distribution
    # (derived from manifest.json "key" field). Default so the vanilla call
    # works without docs lookup. Override only if you fork the extension.
    [ValidatePattern('^[a-p]{32}$')]
    [string]$ExtensionId = 'eheocihmlppcophaeakmdenhgcookkab',

    # Update manifest is hosted on the published gh-pages of the upstream
    # repo. Default so single-tenant operators don't need to type the URL.
    [Parameter(ParameterSetName = 'Install')]
    [string]$UpdateUrl = 'https://knudsenmorten.github.io/PIM4EntraPS/updates.xml',

    # Update channel. 'Test' targets the test extension id + updates-test.xml so this
    # writes the SEPARATE test forcelist + managed catalog (same tenant catalog as
    # released; only the id/URL differ). 'Released' (default) is unchanged. Mirrors
    # Update-PimActivator-Extension.ps1.
    [Parameter()]
    [ValidateSet('Released','Test')]
    [string]$Channel = 'Released',

    [Parameter()]
    [ValidateSet('Machine', 'User')]
    [string]$Scope = 'Machine',

    [Parameter()]
    [ValidateSet('Edge', 'Chrome', 'Both')]
    [string]$Browser = 'Both',

    # Optional path to the tenant catalog JSON. v2.4.111 removed the previous
    # sibling-file default ('discovered-tenant-catalog.json' next to this
    # script) after a customer-tenant incident where that file -- left over
    # in a working dir from a different tenant -- got picked up silently and
    # written the vendor's own tenant id + client id into the customer's registry.
    # Now: when omitted (the common case), the script auto-discovers the
    # tenant + PIM Activator app registration from the LIVE Microsoft Graph
    # tenant you sign in to (a browser sign-in opens, plain REST, no module, if not already
    # connected).
    # That guarantees the catalog matches the tenant the operator is signed
    # into right now -- never a stale file from elsewhere. Pass an explicit
    # path to override, or -SkipTenantCatalog to skip the catalog write
    # entirely (still writes the forcelist / sources / settings policies).
    [Parameter(ParameterSetName = 'Install')]
    [string]$CatalogJsonPath,

    [Parameter(ParameterSetName = 'Install')]
    [switch]$SkipTenantCatalog,

    # Opt-in: also write ExtensionInstallAllowlist for our id. Only useful
    # in environments where the admin has set ExtensionInstallBlocklist='*'.
    # Default OFF since this caused "can't install any other extension" on
    # some Chromium versions where the presence of an Allowlist key with
    # a single entry was interpreted as "deny everything else" (2026-06-10).
    [Parameter(ParameterSetName = 'Install')]
    [switch]$WriteAllowlist,

    # Override the per-tenant activation defaults the popup pre-fills.
    # -DefaultJustification sets the justification text; -DefaultDurationHours
    # sets the activation length (whole hours). When supplied they OVERWRITE
    # whatever the resolved catalog carried -- the value from -CatalogJsonPath
    # or the auto-discover fallback ('Change in infrastructure' / 8h) -- on
    # EVERY tenant entry written to the registry. Omit them to keep the
    # catalog's own values. Additive + opt-in: absent => nothing changes.
    [Parameter(ParameterSetName = 'Install')]
    [string]$DefaultJustification,

    [Parameter(ParameterSetName = 'Install')]
    [ValidateRange(1, 24)]
    [int]$DefaultDurationHours,

    # Per-DEVICE cap on auto-activation (2026-09-23): writes ...\3rdparty\extensions\<id>\policy\
    # autoActivateMaxGroups (REG_DWORD). 0 = auto-activation off on this machine; N = at most N groups;
    # -1 = remove the value (no limit). Not passed = the machine's current value is left alone.
    # Written for BOTH PIM Activator extensions (production and test), like the Intune Remediation (owner 2026-10-22:
    # "the script must support the new features like max 3 activations").
    [Parameter(ParameterSetName = 'Install')]
    [ValidateRange(-1, 100)]
    [int]$AutoActivateMaxGroups,

    # ACT-ENDTIME (owner 2026-10-31): per-DEVICE end-of-day time, ...\policy\activationEndTime (REG_SZ 'HH:MM').
    # 'none' = remove the value. Not passed = left alone. Both extensions, as above.
    [Parameter(ParameterSetName = 'Install')]
    [ValidatePattern('^(([01][0-9]|2[0-3]):[0-5][0-9]|none)$')]
    [string]$ActivationEndTime,

    # Per-DEVICE "click again to confirm" threshold for bulk activation: ...\policy\bulkActivateConfirmThreshold
    # (REG_DWORD). 1-100 = the threshold; -1 = remove the value (the extension's default). Not passed = left alone.
    # A tenant's own bulkActivateConfirmThreshold in the catalog wins over it. Both extensions, as above.
    [Parameter(ParameterSetName = 'Install')]
    [ValidateRange(-1, 100)]
    [int]$BulkActivateConfirmThreshold,

    # Optional name filters for THIS tenant's catalog entry (with -TenantId / -ClientId), the same as the Remediation's:
    # the popup lists only groups / Entra roles / Azure roles whose names start with them.
    [Parameter(ParameterSetName = 'Install')]
    [string]$Prefix = '',
    [Parameter(ParameterSetName = 'Install')]
    [string]$EntraPrefix = '',
    [Parameter(ParameterSetName = 'Install')]
    [string]$AzurePrefix = '',

    [Parameter(ParameterSetName = 'Install')]
    [ValidatePattern('^[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}$')]
    [string]$ClientId,

    [Parameter(ParameterSetName = 'Install')]
    [string]$AppDisplayName = 'PIM Activator',

    # 97.2 (owner 2026-10-08, "one download + one command, nothing else"): with -TenantId AND -ClientId the tenant
    # catalog is written from these values directly -- no sign-in, no -CatalogJsonPath file. -TenantName is the name
    # admins see (default 'PIM'). The PIM Manager's Operations > PIM Activator page fills all three.
    [Parameter(ParameterSetName = 'Install')]
    [ValidatePattern('^[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}$')]
    [string]$TenantId,

    [Parameter(ParameterSetName = 'Install')]
    [string]$TenantName = 'PIM',

    # Optional multi-tenant catalog: more tenants (JSON array of { name, tenantId, clientId, ... }) added after this one.
    [Parameter(ParameterSetName = 'Install')]
    [string]$AdditionalTenantsJson = '',

    [Parameter(Mandatory, ParameterSetName = 'Uninstall')]
    [switch]$Uninstall
)

$ErrorActionPreference = 'Stop'

# 12.7 run frame: "<Script> version <x.y.z> - documentation: <page>" as the first line (100.52) + a transcript in the temp folder (its path printed at the end).
# To run it on a server on its own, use the standalone download: it has this helper (and the two below) inlined.
# ===== BEGIN inlined helper: ..\setup\_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: ..\setup\_PimScriptDoc.ps1 =====
$null = Start-PimScriptRun -Script 'Deploy-PimActivatorClient'
try {
$_preview = [bool]$WhatIfPreference
if ($_preview) { Write-Host 'PREVIEW (-WhatIf): reads this machine''s policies; every registry value it would set or remove is listed, none is written.' -ForegroundColor Yellow }

# ---- Channel defaults (Test writes the SEPARATE test forcelist + catalog) ----
if ($Channel -eq 'Test') {
    if (-not $PSBoundParameters.ContainsKey('ExtensionId')) { $ExtensionId = 'glldnbmjpdkjemcnficagdhgienfdpoo' }
    if (-not $PSBoundParameters.ContainsKey('UpdateUrl'))   { $UpdateUrl   = 'https://knudsenmorten.github.io/PIM4EntraPS/updates-test.xml' }
    Write-Host "Channel = TEST -> id $ExtensionId, $UpdateUrl" -ForegroundColor Yellow
}
# the limits go to BOTH PIM Activator extensions (production, test), whichever channel this run installs
$limitExtensionIds = @('eheocihmlppcophaeakmdenhgcookkab', 'glldnbmjpdkjemcnficagdhgienfdpoo')
if (("$Prefix$EntraPrefix$AzurePrefix".Trim()) -and -not ($TenantId -and $ClientId)) {
    Write-Warning '-Prefix / -EntraPrefix / -AzurePrefix go into the tenant catalog built from -TenantId and -ClientId; without both they are not used.'
}

# Troubleshooting banner (script + solution + module + PS versions). Guarded:
# this script is sometimes copied to a client box standalone, without the
# sibling _PimActivatorAuth.ps1 -- skip the banner rather than break.
# No modules (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): the helper is plain REST + a browser
# sign-in. Loaded with the literal form below so Build-PimSupportScripts inlines it into the standalone download.
try {
# ===== BEGIN inlined helper: _PimActivatorAuth.ps1 =====
# _PimActivatorAuth.ps1 -- shared Microsoft Graph sign-in for the pim-activator deploy scripts. Dot-source from a
# sibling script; defines functions only (no side effects on load).
#
# NO MODULES (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): plain REST + .NET, nothing from
# the PowerShell Gallery. The token lives in a script variable ($script:PaGraphToken, see _PimActivatorBackend.ps1) and
# every Graph call goes through Invoke-PaGraph. Three ways in:
#   * Interactive: browser sign-in, auth code + PKCE on a localhost loopback (the first-party "Microsoft Graph Command
#     Line Tools" public client, so no extra app registration). Edge is launched explicitly -- servers whose default
#     browser is legacy Internet Explorer mangle the redirect -- with the system default browser as the fallback when
#     Edge is not installed.
#   * App-only: -AppId + -CertificateThumbprint + -TenantId. The token is minted here: client_credentials with an RS256
#     client assertion signed by the certificate (Cert:\CurrentUser\My or Cert:\LocalMachine\My). Windows PowerShell
#     5.1 and PowerShell 7.
#   * A token you already have (-AccessToken), for automation.
# Also used by Deploy-PimActivatorClient.ps1 for its version banner only.

# VERSION lives at the PIM4EntraPS solution root, two levels up from tools/pim-activator/. A standalone (built) copy
# has no VERSION file next to it: then the version is read from the header line the build writes into the file.
function Get-PimActivatorSolutionVersion {
    $f = Join-Path $PSScriptRoot '..\..\VERSION'
    if (Test-Path -LiteralPath $f) { return 'v' + (Get-Content -LiteralPath $f -TotalCount 1).Trim() }
    foreach ($self in @($PSCommandPath, $MyInvocation.ScriptName) | Where-Object { $_ }) {
        try {
            $head = @(Get-Content -LiteralPath $self -TotalCount 5 -ErrorAction Stop)
            foreach ($l in $head) { if ($l -match '^# PIM Manager (\S+) --') { return 'v' + $Matches[1] + ' (standalone)' } }
        } catch { }
    }
    '(VERSION file not found)'
}

# Troubleshooting banner: script + solution version and the PowerShell runtime. -GraphModules / -AzModules are still
# accepted for scripts that use those modules on an optional path (Deploy-PimActivatorClient.ps1); they are REPORTED
# (installed version or "not installed"), never loaded. -GraphOptional is accepted for compatibility and changes
# nothing any more -- nothing here can fail on a missing module.
function Show-PimActivatorBanner {
    param(
        [Parameter(Mandatory)][string]$ScriptName,
        [string[]]$GraphModules,
        [string[]]$AzModules,
        [switch]$GraphOptional
    )
    Write-Host "$ScriptName -- PIM Manager $(Get-PimActivatorSolutionVersion)" -ForegroundColor Cyan
    foreach ($m in @(@($GraphModules) + @($AzModules) | Where-Object { $_ })) {
        $mod = Get-Module -Name $m -ErrorAction SilentlyContinue | Select-Object -First 1
        if (-not $mod) { $mod = Get-Module -ListAvailable -Name $m -ErrorAction SilentlyContinue | Sort-Object Version -Descending | Select-Object -First 1 }
        $v = if ($mod) { "v$($mod.Version)" } else { 'not installed' }
        Write-Host ("{0,-11}: {1}" -f $m, $v) -ForegroundColor Cyan
    }
    Write-Host "PowerShell : $($PSVersionTable.PSVersion) ($($PSVersionTable.PSEdition))" -ForegroundColor Cyan
}

# The guidance shown whenever a host cannot complete the sign-in.
function Get-PaBrokenAuthHelp {
    @"
This host cannot complete the sign-in. Known causes + fixes, in order of likelihood:
  1. The system default browser is legacy Internet Explorer, which mangles the auth redirect. This script launches Microsoft Edge explicitly (-UseEdge, the default); if you passed -UseEdge:`$false, drop it. To fix the host itself: Settings > Default apps > set Microsoft Edge as default for HTTP/HTTPS.
  2. Stale pending sign-in tabs answering the listener with an old state: close ALL browser windows, retry once.
  3. Something on this host blocks the localhost listener the browser answers to (a local firewall or proxy rule for 127.0.0.1): allow it, or run this script from another machine where sign-in works (it only talks to Microsoft Graph -- nothing tenant-side requires this host).
  4. Bring a token: sign in somewhere that works, mint a Microsoft Graph access token with Application.ReadWrite.All and DelegatedPermissionGrant.ReadWrite.All, and pass it with -AccessToken <token> (valid ~1 hour).
"@
}

# base64url (RFC 7515 section 2): no padding, URL-safe alphabet.
function ConvertTo-PaB64Url {
    param([Parameter(Mandatory)][byte[]]$Bytes)
    [Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_')
}
function ConvertFrom-PaB64Url {
    param([Parameter(Mandatory)][string]$Text)
    $s = $Text.Replace('-', '+').Replace('_', '/')
    switch ($s.Length % 4) { 2 { $s += '==' } 3 { $s += '=' } }
    [Convert]::FromBase64String($s)
}

# The claims of a JWT (claims read only -- Graph validates the token; tid/upn/wids/scp/roles/exp are read). $null when the
# string is not a readable JWT (an opaque token, or garbage).
function ConvertFrom-PaJwtClaims {
    param([AllowEmptyString()][string]$Token)
    if (-not $Token) { return $null }
    $parts = $Token -split '\.'
    if ($parts.Count -lt 2) { return $null }
    try { [Text.Encoding]::UTF8.GetString((ConvertFrom-PaB64Url $parts[1])) | ConvertFrom-Json } catch { $null }
}

# Seconds since the Unix epoch (5.1-safe: no DateTimeOffset.ToUnixTimeSeconds dependency on the caller).
function Get-PaUnixTime {
    param([datetime]$Utc = [datetime]::UtcNow)
    if ($Utc.Kind -eq [DateTimeKind]::Unspecified) { $Utc = [datetime]::SpecifyKind($Utc, [DateTimeKind]::Utc) }
    [long][Math]::Floor(($Utc.ToUniversalTime() - (New-Object datetime(1970, 1, 1, 0, 0, 0, [DateTimeKind]::Utc))).TotalSeconds)
}

# Store a Graph access token as THE session token: claims decoded, expiry noted, renewal recipe kept. -Refresh is a
# plain hashtable (no scriptblock closures -- those cannot see this file's functions): @{ Kind = 'AppOnly'; TenantId;
# ClientId; Thumbprint } or @{ Kind = 'RefreshToken'; RefreshToken; Tenant; Scopes }. None = cannot be renewed (a token
# passed with -AccessToken).
function Set-PaGraphSession {
    param(
        [Parameter(Mandatory)][string]$AccessToken,
        [ValidateSet('Interactive', 'AppOnly', 'ProvidedToken')][string]$AuthType = 'ProvidedToken',
        [int]$ExpiresInSeconds = 0,
        [hashtable]$Refresh
    )
    $script:PaGraphToken  = $AccessToken
    $script:PaTokenClaims = ConvertFrom-PaJwtClaims $AccessToken
    $script:PaAuthType    = $AuthType
    $exp = $null
    if ($script:PaTokenClaims -and $script:PaTokenClaims.PSObject.Properties['exp']) { $exp = (New-Object datetime(1970, 1, 1, 0, 0, 0, [DateTimeKind]::Utc)).AddSeconds([double]$script:PaTokenClaims.exp) }
    elseif ($ExpiresInSeconds -gt 0) { $exp = [datetime]::UtcNow.AddSeconds($ExpiresInSeconds) }
    $script:PaGraphTokenExpiresUtc = $exp
    $script:PaGraphTokenRefresh    = $Refresh
}

# Renew the session token from its recipe (called by Get-PaGraphAccessToken when the token is about to expire).
function Update-PaGraphSession {
    $r = $script:PaGraphTokenRefresh
    if (-not $r) { return }
    switch ($r.Kind) {
        'AppOnly' {
            $tok = Get-PaAppOnlyToken -TenantId $r.TenantId -ClientId $r.ClientId -CertificateThumbprint $r.Thumbprint
            Set-PaGraphSession -AccessToken "$($tok.access_token)" -AuthType AppOnly -ExpiresInSeconds ([int]"0$($tok.expires_in)") -Refresh $r
        }
        'RefreshToken' {
            $tok = Get-PaRefreshedToken -RefreshToken $r.RefreshToken -Tenant $r.Tenant -Scopes $r.Scopes
            if ($tok.refresh_token) { $r.RefreshToken = "$($tok.refresh_token)" }
            Set-PaGraphSession -AccessToken "$($tok.access_token)" -AuthType Interactive -ExpiresInSeconds ([int]"0$($tok.expires_in)") -Refresh $r
        }
    }
}

# PKCE verifier + S256 challenge (RFC 7636).
function New-PaPkcePair {
    $bytes = New-Object byte[] 32
    [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
    $verifier = ConvertTo-PaB64Url $bytes
    $challenge = ConvertTo-PaB64Url ([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::ASCII.GetBytes($verifier)))
    [pscustomobject]@{ Verifier = $verifier; Challenge = $challenge }
}

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

# The authorize URL for the loopback auth-code + PKCE flow (pure, unit-tested).
function New-PaAuthorizeUrl {
    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
    )
    "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&prompt=select_account"
}

# msedge.exe, or $null.
function Get-PaEdgePath {
    @(
        $(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
}

# Microsoft Graph Command Line Tools (first-party public client; the same app the Graph PowerShell SDK signs in with).
function Get-PaGraphCliClientId { '14d82eec-204b-4c2f-b7e8-296a70dab67e' }

# Interactive browser sign-in: auth code + PKCE on a loopback TcpListener (no HttpListener URL-ACL, works non-elevated),
# Edge launched explicitly (default browser when Edge is missing or -UseEdge:$false). Returns the token response.
function Get-PaInteractiveToken {
    param(
        [Parameter(Mandatory)][string[]]$Scopes,
        [string]$Tenant = 'organizations',
        [bool]$UseEdge = $true
    )
    $clientId = Get-PaGraphCliClientId
    $pkce  = New-PaPkcePair
    $state = [guid]::NewGuid().ToString('N')
    $scope = Get-PaDelegatedScopeString -Scopes $Scopes

    # OS-assigned free port; first-party public clients accept any localhost port on the redirect URI.
    $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-PaAuthorizeUrl -Tenant $Tenant -ClientId $clientId -RedirectUri $redirect -Scope $scope -State $state -CodeChallenge $pkce.Challenge

    $query = $null
    try {
        $edge = if ($UseEdge) { Get-PaEdgePath } else { $null }
        if ($edge) {
            Write-Host "Launching Edge for sign-in (loopback listener on $redirect)..." -ForegroundColor Yellow
            Start-Process -FilePath $edge -ArgumentList @('--new-window', $authUrl) -WhatIf:$false   # opening the sign-in page is not a change: -WhatIf still signs in
        } else {
            if ($UseEdge) { Write-Host 'Microsoft Edge not found -- using the default browser.' -ForegroundColor DarkYellow }
            Write-Host "Opening the default browser for sign-in (loopback listener on $redirect)..." -ForegroundColor Yellow
            Start-Process $authUrl -WhatIf:$false
        }
        Write-Host "If no browser opened, open this URL yourself:`n  $authUrl" -ForegroundColor DarkGray
        # SIGNIN-PAGE (owner 2026-10-31, Invardia's Wait-AuthCode fix): only the answer (code / error) ends the wait, every
        # request gets a page, and the page keeps answering 10 s after it (PIM-LoopbackAnswer.ps1; tools/setup/_PimLoopbackAnswer.ps1 is its identical copy for the tools).
        if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: ..\setup\_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: ..\setup\_PimLoopbackAnswer.ps1 =====
        }
        $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 min) waiting for the sign-in redirect from the browser.'
    } finally { foreach ($tcpL in $tcps) { try { $tcpL.Stop() } catch { } } }

    $kv = @{}
    foreach ($pair in ($query -split '&')) {
        $k, $v = $pair -split '=', 2
        $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+', ' ')) } else { '' }
    }
    if ($kv['error'])            { throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])" }
    if ($kv['state'] -ne $state) { throw 'State mismatch on the loopback redirect -- the response did not come from this sign-in attempt. Close ALL browser windows and retry.' }
    if (-not $kv['code'])        { throw 'Sign-in redirect 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
    }
}

# Renew a delegated token with its refresh token (same public client, same scopes).
function Get-PaRefreshedToken {
    param([Parameter(Mandatory)][string]$RefreshToken, [Parameter(Mandatory)][string]$Tenant, [Parameter(Mandatory)][string[]]$Scopes)
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id     = (Get-PaGraphCliClientId)
        grant_type    = 'refresh_token'
        refresh_token = $RefreshToken
        scope         = (Get-PaDelegatedScopeString -Scopes $Scopes)
    }
}

# The certificate (with its private key) by thumbprint: CurrentUser\My first, then LocalMachine\My.
function Get-PaCertificate {
    param([Parameter(Mandatory)][string]$Thumbprint)
    $tp = ($Thumbprint -replace '[^0-9A-Fa-f]', '').ToUpperInvariant()
    foreach ($loc in 'CurrentUser', 'LocalMachine') {
        $store = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', $loc)
        try {
            $store.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadOnly)
            $hit = @($store.Certificates.Find([System.Security.Cryptography.X509Certificates.X509FindType]::FindByThumbprint, $tp, $false)) | Select-Object -First 1
        } finally { $store.Close() }
        if ($hit) {
            if (-not $hit.HasPrivateKey) { throw "Certificate $tp found in Cert:\$loc\My but without its private key -- app-only sign-in needs the key." }
            return $hit
        }
    }
    throw "Certificate $tp not found in Cert:\CurrentUser\My or Cert:\LocalMachine\My."
}

# RS256 signature over $Data with the certificate's private key. Old CSP-stored keys (PROV_RSA_FULL) cannot hash SHA-256;
# for those the same key container is reopened under the enhanced (AES) provider, the classic 5.1 workaround.
function Invoke-PaRsaSha256Sign {
    param([Parameter(Mandatory)][System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate, [Parameter(Mandatory)][byte[]]$Data)
    $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($Certificate)
    if (-not $rsa) { throw "Certificate $($Certificate.Thumbprint) has no RSA private key." }
    try {
        return $rsa.SignData($Data, [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
    } catch {
        if ($rsa -isnot [System.Security.Cryptography.RSACryptoServiceProvider]) { throw }
        $info = $rsa.CspKeyContainerInfo
        $cp = New-Object System.Security.Cryptography.CspParameters(24, 'Microsoft Enhanced RSA and AES Cryptographic Provider', $info.KeyContainerName)
        $cp.KeyNumber = [int]$info.KeyNumber
        $cp.Flags = [System.Security.Cryptography.CspProviderFlags]::UseExistingKey
        if ($info.MachineKeyStore) { $cp.Flags = $cp.Flags -bor [System.Security.Cryptography.CspProviderFlags]::UseMachineKeyStore }
        $csp = New-Object System.Security.Cryptography.RSACryptoServiceProvider($cp)
        try { return $csp.SignData($Data, [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1) } finally { $csp.Dispose() }
    }
}

# The client assertion for client_credentials (RFC 7523): header {alg RS256, typ JWT, x5t = base64url(SHA-1 cert hash)},
# claims {aud = the v2 token endpoint, iss = sub = client id, jti, nbf, exp (10 min)}. Pure apart from the signature.
function New-PaClientAssertion {
    param(
        [Parameter(Mandatory)][System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate,
        [Parameter(Mandatory)][string]$ClientId,
        [Parameter(Mandatory)][string]$TenantId,
        [datetime]$NowUtc = [datetime]::UtcNow,
        [int]$LifetimeSeconds = 600
    )
    $now = Get-PaUnixTime -Utc $NowUtc
    $header = [ordered]@{ alg = 'RS256'; typ = 'JWT'; x5t = (ConvertTo-PaB64Url $Certificate.GetCertHash()) }
    $claims = [ordered]@{
        aud = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
        iss = $ClientId
        sub = $ClientId
        jti = [guid]::NewGuid().ToString()
        nbf = $now
        exp = $now + $LifetimeSeconds
    }
    $enc = [Text.Encoding]::UTF8
    $unsigned = (ConvertTo-PaB64Url $enc.GetBytes(($header | ConvertTo-Json -Compress))) + '.' + (ConvertTo-PaB64Url $enc.GetBytes(($claims | ConvertTo-Json -Compress)))
    $sig = Invoke-PaRsaSha256Sign -Certificate $Certificate -Data $enc.GetBytes($unsigned)
    $unsigned + '.' + (ConvertTo-PaB64Url $sig)
}

# App-only Graph token: client_credentials with the certificate assertion. Returns the token response.
function Get-PaAppOnlyToken {
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$CertificateThumbprint)
    $cert = Get-PaCertificate -Thumbprint $CertificateThumbprint
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id             = $ClientId
        grant_type            = 'client_credentials'
        scope                 = 'https://graph.microsoft.com/.default'
        client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
        client_assertion      = (New-PaClientAssertion -Certificate $cert -ClientId $ClientId -TenantId $TenantId)
    }
}

# Active directory role template ids from the session token's wids claim (the user's ACTIVE roles at issuance, readable
# without any directory-read scope -- unlike /me/memberOf, which hides roles from lean tokens). $null = unknown (no
# token, or no wids claim), not "no roles".
function Get-PaTokenRoleIds {
    if ($script:PaTokenClaims -and $script:PaTokenClaims.PSObject.Properties['wids']) { return @($script:PaTokenClaims.wids) }
    $null
}

# Ensure the session token carries at least one of the given directory role template ids. Typical failure: the operator
# activated the PIM role AFTER signing in, so the token predates the activation -- then run -Reconnect ONCE to mint a
# fresh token, and re-check. Without -Reconnect (a token passed in, which cannot be renewed here) it stops with the
# fix. -SoftFail warns and continues instead of throwing. No-op when the session's roles cannot be determined.
function Assert-PaSessionRole {
    param(
        [Parameter(Mandatory)][string[]]$AnyOfRoleIds,
        [Parameter(Mandatory)][string]$RoleDescription,
        [scriptblock]$Reconnect,
        [switch]$SoftFail
    )
    $wids = Get-PaTokenRoleIds
    if ($null -eq $wids) { return }   # cannot introspect -- let the API be the judge
    if (@($wids | Where-Object { $_ -in $AnyOfRoleIds }).Count -gt 0) { return }

    Write-Host "Session token does not carry $RoleDescription." -ForegroundColor Yellow
    if (-not $Reconnect) {
        if ($SoftFail) { Write-Host 'Continuing anyway (expect a 403 if the role is really missing).' -ForegroundColor DarkYellow; return }
        throw "The access token does not carry $RoleDescription. Activate the role in PIM, mint a NEW token after the activation, and run this script again."
    }
    Write-Host 'If you activated it in PIM after signing in, the token predates the activation -- signing in again to pick it up...' -ForegroundColor Yellow
    & $Reconnect

    $wids = Get-PaTokenRoleIds
    if ($null -eq $wids -or @($wids | Where-Object { $_ -in $AnyOfRoleIds }).Count -gt 0) { return }
    if ($SoftFail) {
        Write-Host "Still no $RoleDescription in the fresh token -- continuing anyway (a scoped RBAC assignment may still authorize the writes; expect a 403 otherwise)." -ForegroundColor DarkYellow
        return
    }
    throw "Even after a fresh sign-in, the session does not carry $RoleDescription. Activate it in PIM, wait for the activation to complete, then re-run this script."
}

# One-stop sign-in. Establishes the session token (Set-PaGraphSession) and returns a context object:
#   TenantId, Account, ClientId, AuthType (Interactive | AppOnly | ProvidedToken), Scopes (delegated scp), Roles (app roles).
#   * -AccessToken           : use that token as is (no renewal; scope check reported, not enforced).
#   * -AppId + -CertificateThumbprint (+ -TenantId) : app-only; the app needs the equivalent APPLICATION permissions
#                              (Application.ReadWrite.All; DelegatedPermissionGrant.ReadWrite.All for consent grants).
#   * otherwise              : interactive browser sign-in (Edge unless -UseEdge:$false).
# Then a cheap probe (/me, or one application for app-only) proves the token works before any write.
function Connect-PimActivatorGraph {
    param(
        [Parameter(Mandatory)][string[]]$RequiredScopes,
        [string]$TenantId,
        [bool]$UseEdge = $true,
        [string]$AppId,
        [string]$CertificateThumbprint,
        [string]$AccessToken
    )
    $isGuid = { param($s) $s -match '^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$' }

    if ($AccessToken) {
        Set-PaGraphSession -AccessToken $AccessToken -AuthType ProvidedToken
        Write-Host 'Using the access token passed with -AccessToken (no renewal -- valid ~1 hour from when it was minted).' -ForegroundColor Cyan
    } elseif ($AppId -and $CertificateThumbprint) {
        if (-not $TenantId) { throw 'App-only sign-in requires -TenantId.' }
        $recipe = @{ Kind = 'AppOnly'; TenantId = $TenantId; ClientId = $AppId; Thumbprint = $CertificateThumbprint }
        try { $tok = Get-PaAppOnlyToken -TenantId $TenantId -ClientId $AppId -CertificateThumbprint $CertificateThumbprint }
        catch { throw "App-only token request failed (app $AppId, certificate $CertificateThumbprint, tenant $TenantId): $($_.Exception.Message)" }
        Set-PaGraphSession -AccessToken "$($tok.access_token)" -AuthType AppOnly -ExpiresInSeconds ([int]"0$($tok.expires_in)") -Refresh $recipe
    } else {
        $tenant = if ($TenantId) { $TenantId } else { 'organizations' }
        Write-Host "Signing in to Microsoft Graph in the browser (scopes: $($RequiredScopes -join ', '))..." -ForegroundColor Yellow
        try { $tok = Get-PaInteractiveToken -Scopes $RequiredScopes -Tenant $tenant -UseEdge $UseEdge }
        catch { throw ("Sign-in failed: $($_.Exception.Message)`n$(Get-PaBrokenAuthHelp)") }
        $refresh = $null
        if ($tok.refresh_token) { $refresh = @{ Kind = 'RefreshToken'; RefreshToken = "$($tok.refresh_token)"; Tenant = $tenant; Scopes = $RequiredScopes } }
        Set-PaGraphSession -AccessToken "$($tok.access_token)" -AuthType Interactive -ExpiresInSeconds ([int]"0$($tok.expires_in)") -Refresh $refresh
        Write-Host 'Signed in (token valid ~1 hour, renewed automatically).' -ForegroundColor Green
    }

    $c = $script:PaTokenClaims
    $ctx = [pscustomobject]@{
        TenantId = $(if ($c -and $c.PSObject.Properties['tid']) { "$($c.tid)" } elseif (& $isGuid $TenantId) { $TenantId } else { $null })
        Account  = $(if ($c) { foreach ($n in 'upn', 'preferred_username', 'unique_name', 'app_displayname') { if ($c.PSObject.Properties[$n] -and $c.$n) { "$($c.$n)"; break } } })
        ClientId = $(if ($c -and $c.PSObject.Properties['appid']) { "$($c.appid)" } elseif ($c -and $c.PSObject.Properties['azp']) { "$($c.azp)" } else { $AppId })
        AuthType = $script:PaAuthType
        Scopes   = @($(if ($c -and $c.PSObject.Properties['scp']) { "$($c.scp)" -split ' ' | Where-Object { $_ } }))
        Roles    = @($(if ($c -and $c.PSObject.Properties['roles']) { $c.roles }))
    }

    if ($TenantId -and (& $isGuid $TenantId) -and $ctx.TenantId -and $ctx.TenantId -ne $TenantId) {
        throw "Signed in to tenant $($ctx.TenantId) but -TenantId says $TenantId. Sign in to the correct tenant (or fix -TenantId)."
    }

    if ($ctx.AuthType -eq 'AppOnly') {
        try { Invoke-PaGraph -Method GET -Path '/applications?$top=1&$select=id' | Out-Null }
        catch { throw "App-only token minted but a test read failed: $($_.Exception.Message)" }
        Write-Host "Connected app-only as appId $($ctx.ClientId) in tenant $($ctx.TenantId)." -ForegroundColor Green
        return $ctx
    }

    if ($ctx.AuthType -eq 'ProvidedToken' -and $ctx.Roles.Count -gt 0 -and $ctx.Scopes.Count -eq 0) {
        Write-Host 'The -AccessToken is an app-only token: skipping the delegated scope check.' -ForegroundColor DarkYellow
        try { Invoke-PaGraph -Method GET -Path '/applications?$top=1&$select=id' | Out-Null }
        catch { throw "The -AccessToken was rejected: $($_.Exception.Message)" }
        return $ctx
    }

    $missing = @($RequiredScopes | Where-Object { $_ -notin $ctx.Scopes })
    if ($missing.Count -gt 0 -and $ctx.Scopes.Count -gt 0) {
        $msg = "The token is missing required delegated scopes: $($missing -join ', ')."
        if ($ctx.AuthType -eq 'Interactive') { throw "$msg Consent to them for 'Microsoft Graph Command Line Tools' (an administrator may have to grant it) and run again." }
        Write-Host "$msg Continuing -- calls that need them will fail with 403." -ForegroundColor DarkYellow
    }

    try {
        $me = Invoke-PaGraph -Method GET -Path '/me?$select=id,userPrincipalName'
        if (-not $ctx.Account -and $me) { $ctx.Account = "$($me.userPrincipalName)" }
    } catch {
        if ($ctx.AuthType -eq 'ProvidedToken') {
            throw ("The -AccessToken was rejected: $($_.Exception.Message)`nTokens expire after ~1 hour -- mint a fresh one.")
        }
        throw ("Signed in, but Microsoft Graph rejected the token: $($_.Exception.Message)`n$(Get-PaBrokenAuthHelp)")
    }
    $ctx
}

# ===== END inlined helper: _PimActivatorAuth.ps1 =====
} catch { Write-Warning "the sign-in helper _PimActivatorAuth.ps1 could not be loaded ($($_.Exception.Message)) -- the live tenant lookup is skipped; pass -CatalogJsonPath, or use the standalone download https://invardia.com/support/pim/Deploy-PimActivatorClient.ps1" }
if (Get-Command Show-PimActivatorBanner -ErrorAction SilentlyContinue) { Show-PimActivatorBanner -ScriptName 'Deploy-PimActivatorClient' }

# HKLM requires admin. Fail fast with a clear message instead of letting
# New-Item fault out mid-write with an opaque registry-permission error.
if ($Scope -eq 'Machine') {
    $isAdmin = ([Security.Principal.WindowsPrincipal]([Security.Principal.WindowsIdentity]::GetCurrent())).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
    if (-not $isAdmin -and $_preview) {
        Write-Warning '-Scope Machine writes to HKLM and needs an elevated session to APPLY; this preview only reads, so it continues.'
    } elseif (-not $isAdmin) {
        throw "-Scope Machine writes to HKLM and requires elevation. Re-run from an elevated PowerShell session, or pass -Scope User to write only the current-user HKCU forcelist."
    }
}

# ---------------------------------------------------------------------------
# Build the list of policy roots we'll operate on, one per targeted browser.
# Edge   : SOFTWARE\Policies\Microsoft\Edge
# Chrome : SOFTWARE\Policies\Google\Chrome
# Both browsers read identical key names under their own root.
# ---------------------------------------------------------------------------

$hiveRoot = if ($Scope -eq 'Machine') { 'HKLM:' } else { 'HKCU:' }

$policyRoots = New-Object System.Collections.Generic.List[object]
if ($Browser -in @('Edge','Both')) {
    $policyRoots.Add([pscustomobject]@{ Name = 'Edge';   Path = "$hiveRoot\SOFTWARE\Policies\Microsoft\Edge"; Rel = 'SOFTWARE\Policies\Microsoft\Edge' })
}
if ($Browser -in @('Chrome','Both')) {
    $policyRoots.Add([pscustomobject]@{ Name = 'Chrome'; Path = "$hiveRoot\SOFTWARE\Policies\Google\Chrome"; Rel = 'SOFTWARE\Policies\Google\Chrome' })
}

function New-PolicyKey {
    param([string]$Path)
    if (-not (Test-Path -LiteralPath $Path)) { New-Item -Path $Path -Force | Out-Null }
}

function Set-Reg {
    param([string]$Path, [string]$Name, $Value, [Microsoft.Win32.RegistryValueKind]$Kind = [Microsoft.Win32.RegistryValueKind]::String)
    New-PolicyKey -Path $Path
    New-ItemProperty -Path $Path -Name $Name -Value $Value -PropertyType $Kind -Force | Out-Null
}

# ---------------------------------------------------------------------------
# WHERE our rows go (BUG-182 / BUG-220). The list policies are SHARED with the
# org's own force-installed extensions, and ExtensionSettings is ONE dictionary
# per browser. The slot + merge logic lives in _PimActivatorHybridPolicy.ps1 and
# is the same code Deploy-PimActivatorHybrid.ps1 -Target LocalGpo runs, so the
# two writers produce one layout.
#
# The slot USED to be ([Math]::Abs($ExtensionId.GetHashCode()) % 9000) + 1000.
# String.GetHashCode() is randomised per PROCESS on .NET Core (pwsh 7), so every
# run picked a different slot: re-runs piled up duplicate rows and -Uninstall
# looked in the wrong slot and removed nothing (the build host, 2026-09-18: four rows for
# the released id at 1590 / 3077 / 5148 / 7772).
# Now: our row goes in the lowest slot nobody else uses (reusing ours if it is
# already there); every other row carrying our id is removed.
# ---------------------------------------------------------------------------
try {
# ===== BEGIN inlined helper: _PimActivatorHybridPolicy.ps1 =====
<#
.SYNOPSIS
    Pure, offline registry-policy/plan BUILDER for the PIM Activator hybrid
    (on-prem / standalone) deploy. NO network, NO DC, NO admin, NO modules.

.DESCRIPTION
    This is the shared core behind Deploy-PimActivatorHybrid.ps1's three
    -Target modes (Json / DomainGpo / LocalGpo). It turns an MSP's
    multi-tenant Activator config into the EXACT same client-side managed
    configuration the fleet path uses (Edge management service + the Intune Remediation in intune-remediation\), expressed as
    plain HKLM registry policy values so the same plan drives:

      * LocalGpo  -- write the values straight into the local machine's
                     policy hive (HKLM\SOFTWARE\Policies\...), no domain.
      * DomainGpo -- feed the values to New-GPO / Set-GPRegistryValue.
      * Json      -- emit the managed-config JSON artifact for inspection.

    PARITY CONTRACT (must match the documented managed config and intune-remediation\Remediate-PimActivator.ps1):
    Per included browser (Edge and/or Chrome) the Intune deploy pushes FOUR
    client policies. Their on-device HKLM registry shapes are:

      1. ExtensionInstallForcelist  (REG_SZ list, numbered value names "1","2"..)
           key:   SOFTWARE\Policies\<vendor>\ExtensionInstallForcelist
           value: "<extId>;<updateUrl>"
      2. ExtensionInstallSources    (REG_SZ list)
           key:   SOFTWARE\Policies\<vendor>\ExtensionInstallSources
           value: "<sourcePattern>"
      3. ExtensionSettings          (REG_SZ, single JSON string)
           key:   SOFTWARE\Policies\<vendor>
           value name: ExtensionSettings
           value: { "<extId>": { installation_mode, update_url,
                                  runtime_allowed_hosts:["<all_urls>"] } }
      4. tenantCatalog              (REG_SZ, single JSON string) via the
         3rd-party extension policy path (the Intune Remediation
         writes here)
           key:   SOFTWARE\Policies\<vendor>\3rdparty\extensions\<extId>\policy
           value name: tenantCatalog
           value: JSON array of tenant entries

    where <vendor> is:
       Edge   -> Microsoft\Edge
       Chrome -> Google\Chrome

    The ExtensionSettings JSON and the forcelist/source row formats are byte
    identical to the documented managed config (and the Remediation's catalog) so all targets
    (and Intune) converge on the same effective client configuration.

    PS 5.1-safe: no ?./??, no RSA.ImportFromPem, no .Contains(string,cmp);
    ConvertTo-Json forced to array shape via -InputObject @(...) (PS 5.1 drops
    the outer [] for a single-element array otherwise).

    Dot-source this file to get the pure functions with NO side effects:
       New-PaHybridConfig          -- validate + normalise a tenant config
       New-PaHybridExtensionSettingsJson
       New-PaHybridForcelistValue
       Get-PaHybridRegistryPlan    -- the full per-browser registry value plan
       ConvertTo-PaHybridManagedConfigObject  -- the -Target Json artifact
       Get-PaPolicyListPlan        -- WHERE our row goes in a Chromium list policy (BUG-182/220)
       Get-PaExtensionSettingsPlan -- MERGE our id into ExtensionSettings (BUG-182)
    plus two small registry helpers shared by the LOCAL writers
    (Deploy-PimActivatorClient.ps1 and Deploy-PimActivatorHybrid.ps1 -Target LocalGpo):
       Read-PaPolicyRegistryState  -- read-only snapshot of what is already there
       Invoke-PaPolicyRegistryOps  -- apply a plan's Set/Remove ops

    🔒 NEVER OVERWRITE AN ORGANISATION'S OWN EXTENSION POLICIES (BUG-182, 2026-09-18).
    The list policies (ExtensionInstallForcelist / Sources / Allowlist) are SHARED keys: the
    org's own force-installed extensions live in the same numbered values. Our row goes into
    the slot that ALREADY holds our id if there is one, else the LOWEST FREE numeric slot --
    never a hard-coded '1' (which replaced the org's first extension) and never a
    GetHashCode() slot (randomised per process on .NET Core, so re-runs piled up duplicates
    and -Uninstall removed nothing; BUG-220 -- measured on the build host 2026-09-18: FOUR rows for
    the released id at 1590 / 3077 / 5148 / 7772). Lowest-free also keeps the list in the
    documented contiguous '1','2',... form, and a removal refills the hole it leaves, so
    the list is valid whether or not a reader tolerates gaps (arbitrary value names do
    appear to be accepted in practice -- the hashed slots installed -- but that is not
    something to depend on).
    ExtensionSettings is ONE dictionary for the whole browser: the org's '*' defaults and
    their other extensions' entries are MERGED with ours, never replaced. Both local
    writers use this one layout, so they can no longer disagree.
#>

# Vendor registry sub-paths under HKLM\SOFTWARE\Policies, keyed by our browser
# label.
$script:PaHybridVendorPath = @{
    Edge   = 'Microsoft\Edge'
    Chrome = 'Google\Chrome'
}

function Get-PaEntryProp {
    <#
    .SYNOPSIS
        Read a named property from a tenant entry that may be a hashtable OR a
        PSCustomObject (ConvertFrom-Json). Returns $null when absent.
    .DESCRIPTION
        A plain function (not a scriptblock) on purpose -- see the note in
        New-PaHybridConfig: a `& {scriptblock}` would inherit the caller's
        $WhatIfPreference and PS would emit a "What if: Retrieve the value..."
        line per property read under -WhatIf.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)]$Entry, [Parameter(Mandatory)][string]$Name)
    # Pure read -- never a confirmable op; pin WhatIf off so PSObject property
    # access doesn't surface "What if: Retrieve the value..." under -WhatIf.
    $WhatIfPreference = $false
    if ($Entry -is [System.Collections.IDictionary]) {
        if ($Entry.Contains($Name)) { return $Entry[$Name] }
        return $null
    }
    $p = $Entry.PSObject.Properties[$Name]
    if ($p) { return $p.Value }
    return $null
}

function New-PaHybridConfig {
    <#
    .SYNOPSIS
        Validate + normalise an MSP multi-tenant Activator config (parsed JSON)
        into the catalog array the registry plan + JSON artifact consume.

    .DESCRIPTION
        Accepts EITHER:
          * a bare array of tenant entries  (the same shape the Intune
            -CatalogJsonPath / sample-tenant-catalog.json uses), OR
          * an object wrapper  { tenants: [ ... ] }  (a friendlier top-level
            shape for the hybrid UNC config so an MSP can add file-level
            metadata next to the array).

        Each tenant entry MUST carry: name, tenantId, clientId.
        Optional per-entry keys (passed through verbatim, mirroring the
        managed-schema.json tenantCatalog contract): defaultJustification,
        defaultDurationHours, prefix, entraPrefix, azurePrefix, groupNameFilter,
        entraGroupRegex, azureGroupRegex, bulkActivateConfirmThreshold.

        Throws a clear error on: empty set, >MaxTenants, missing required
        field, duplicate tenantId, or a non-GUID tenantId/clientId.

    .OUTPUTS
        [pscustomobject[]] normalised tenant catalog (always an array).
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] $InputObject,
        [int]$MaxTenants = 25
    )

    # Pure validation/normalisation -- makes no changes. Pin WhatIf off so a
    # caller running with -WhatIf doesn't turn benign property reads into
    # "What if:" noise.
    $WhatIfPreference = $false

    # Unwrap { tenants: [...] } if present; else treat as the array itself.
    $entries = $null
    if ($InputObject -is [System.Collections.IDictionary]) {
        if ($InputObject.Contains('tenants')) { $entries = $InputObject['tenants'] }
        else { throw "Hybrid config object has no 'tenants' property. Provide either a bare JSON array of tenant entries or an object { ""tenants"": [ ... ] }." }
    } elseif ($null -ne $InputObject -and $null -ne $InputObject.PSObject.Properties['tenants']) {
        $entries = $InputObject.tenants
    } else {
        $entries = $InputObject
    }

    $entries = @($entries)
    if ($entries.Count -eq 0) {
        throw "Tenant config is empty -- expected 1..$MaxTenants tenant entry/entries."
    }
    if ($entries.Count -gt $MaxTenants) {
        throw "Tenant config has $($entries.Count) entries which exceeds the supported maximum of $MaxTenants. Split into multiple deployments or raise -MaxTenants."
    }

    $guidRe = '^[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}$'
    $seenTenantIds = @{}
    $out = New-Object System.Collections.Generic.List[object]

    $idx = 0
    foreach ($e in $entries) {
        $idx++
        if ($null -eq $e) { throw "Tenant entry #$idx is null." }

        # Property accessor that works for both hashtables and PSCustomObjects.
        # NOTE: a plain function call (not a `& {scriptblock}`) -- a scriptblock
        # invoked here would inherit the CALLER's $WhatIfPreference and PS would
        # treat each PSObject property read as a confirmable "Retrieve the value"
        # operation, spamming "What if:" lines when the deploy runs with -WhatIf.
        $name     = [string](Get-PaEntryProp -Entry $e -Name 'name')
        $tenantId = [string](Get-PaEntryProp -Entry $e -Name 'tenantId')
        $clientId = [string](Get-PaEntryProp -Entry $e -Name 'clientId')

        if ([string]::IsNullOrWhiteSpace($name))     { throw "Tenant entry #$idx is missing 'name'." }
        if ([string]::IsNullOrWhiteSpace($tenantId)) { throw "Tenant entry '$name' (#$idx) is missing 'tenantId'." }
        if ([string]::IsNullOrWhiteSpace($clientId)) { throw "Tenant entry '$name' (#$idx) is missing 'clientId'." }
        if ($tenantId -notmatch $guidRe) { throw "Tenant entry '$name' (#$idx) has a malformed tenantId '$tenantId' (expected a GUID)." }
        if ($clientId -notmatch $guidRe) { throw "Tenant entry '$name' (#$idx) has a malformed clientId '$clientId' (expected a GUID)." }

        $tidKey = $tenantId.ToLowerInvariant()
        if ($seenTenantIds.ContainsKey($tidKey)) {
            throw "Duplicate tenantId '$tenantId' (entry '$name', #$idx) -- each tenant must appear once."
        }
        $seenTenantIds[$tidKey] = $true

        # Build a normalised, ordered entry. Required fields first, then any of
        # the known optional keys that are present (verbatim pass-through).
        $norm = [ordered]@{
            name     = $name
            tenantId = $tenantId
            clientId = $clientId
        }
        foreach ($opt in @('defaultJustification','defaultDurationHours','prefix','entraPrefix','azurePrefix','groupNameFilter','entraGroupRegex','azureGroupRegex','bulkActivateConfirmThreshold')) {
            $v = Get-PaEntryProp -Entry $e -Name $opt
            if ($null -ne $v) { $norm[$opt] = $v }
        }
        $out.Add([pscustomobject]$norm)
    }

    return $out.ToArray()
}

function ConvertTo-PaHybridCatalogJson {
    <#
    .SYNOPSIS
        Serialise the normalised catalog to the minified JSON string the
        extension reads as tenantCatalog (always emits a JSON array).
    .DESCRIPTION
        The same compact array the Intune Remediation writes:
        ConvertTo-Json -InputObject @($catalog) -Depth 10 -Compress, so PS 5.1
        never collapses a single-element catalog to a bare object.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)] $Catalog)
    return (ConvertTo-Json -InputObject @($Catalog) -Depth 10 -Compress)
}

function New-PaHybridForcelistValue {
    <#
    .SYNOPSIS
        The single ExtensionInstallForcelist row: "<extId>;<updateUrl>".
        The documented "<extension id>;<update URL>" row.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$ExtensionId,
        [Parameter(Mandatory)][string]$UpdateUrl
    )
    return ("{0};{1}" -f $ExtensionId, $UpdateUrl)
}

function New-PaHybridExtensionSettingsJson {
    <#
    .SYNOPSIS
        The ExtensionSettings policy value (single JSON string keyed by ext id).
    .DESCRIPTION
        The documented force-install entry:
        runtime_allowed_hosts=['<all_urls>'] pre-grants the broad scope so
        Chrome's permission-expansion gate skips the auto-update silent-disable.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$ExtensionId,
        [Parameter(Mandatory)][string]$UpdateUrl,
        # 🔴 THE FLEET-WIDE UNSTICK LEVER. Optional and INERT when omitted, so every existing
        # assignment keeps emitting byte-identical JSON.
        # Measured 2026-09-04: no existing install anywhere had moved to 1.6.124 (published
        # 26 Jun). A laptop sat on 1.6.25 -- the 2026-06-10 build, i.e. the exact release the
        # comment below says froze the fleet -- while the TEST extension on the SAME browser was
        # current, because that one arrived as a FRESH INSTALL rather than an update. Fresh
        # installs work; updates were not landing.
        # `minimum_version_required` is Chrome's own answer to that: an install BELOW the minimum
        # is disabled and pushed to update, instead of quietly sitting on an old build forever.
        # It is the difference between "we hope the update check runs" and "a stale install cannot
        # keep running" -- and it ships as POLICY, so it reaches 10,000 machines without touching
        # one of them.
        # 🪤 Set it to a version you have ALREADY published and verified installable. Naming a
        # version that is not downloadable disables the extension fleet-wide with no way forward.
        [string]$MinimumVersion
    )
    $__cfg = New-PaExtensionSettingsEntry -UpdateUrl $UpdateUrl -MinimumVersion $MinimumVersion
    return (@{ $ExtensionId = $__cfg } | ConvertTo-Json -Depth 5 -Compress)
}

function New-PaExtensionSettingsEntry {
    <#
    .SYNOPSIS
        OUR per-extension ExtensionSettings dictionary (the inner value keyed by our id).
        The one definition New-PaHybridExtensionSettingsJson and the merge both use.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$UpdateUrl,
        [string]$MinimumVersion
    )
    $__cfg = @{
        installation_mode     = 'force_installed'
        update_url            = $UpdateUrl
        runtime_allowed_hosts = @('<all_urls>')
    }
    if ("$MinimumVersion".Trim()) { $__cfg['minimum_version_required'] = "$MinimumVersion".Trim() }
    return $__cfg
}

function New-PaRowMatcher {
    <#
    .SYNOPSIS
        A scriptblock ($data) -> bool that recognises OUR row in a list policy:
          -ExtensionId  a forcelist row "<id>;<url>" (any url) or an allowlist row "<id>"
          -Exact        a row equal to this value (case-insensitive), e.g. a source pattern
    .NOTES
        Built with [scriptblock]::Create on purpose, NOT .GetNewClosure(): a closure copies
        every variable of the calling scope, and on Windows PowerShell 5.1 that THROWS when
        the caller is a script with a validated parameter holding an out-of-range default
        (e.g. [ValidateRange(1,24)][int]$DefaultDurationHours = 0 when not passed).
    #>
    [CmdletBinding()]
    param([string]$ExtensionId, [string]$Exact)
    $WhatIfPreference = $false
    if ($ExtensionId) {
        if ($ExtensionId -notmatch '^[a-p]{32}$') { throw "New-PaRowMatcher: '$ExtensionId' is not a Chromium extension id." }
        return [scriptblock]::Create("param(`$d) (`"`$d`" -like '$ExtensionId;*') -or (`"`$d`" -ieq '$ExtensionId')")
    }
    $lit = "$Exact" -replace "'", "''"
    return [scriptblock]::Create("param(`$d) (`"`$d`" -ieq '$lit')")
}

function Test-PaNumericSlotName {
    # A list-policy value name Chromium treats as a list index: a positive integer.
    param([string]$Name)
    $n = 0
    return ([int]::TryParse("$Name", [ref]$n) -and $n -ge 1 -and "$n" -eq "$Name")
}

function Get-PaPolicyListPlan {
    <#
    .SYNOPSIS
        Pure. Plan where OUR row goes in a Chromium list policy (ExtensionInstallForcelist,
        ExtensionInstallSources, ExtensionInstallAllowlist) -- or how to take it out again --
        WITHOUT touching anybody else's rows (BUG-182 / BUG-220).

    .PARAMETER Existing
        What is already in the list key: value name -> data. $null/empty = nothing there.

    .PARAMETER Value
        The row we want present (e.g. "<id>;<updateUrl>").

    .PARAMETER IsOurs
        Scriptblock ($data) -> bool: which existing rows are OURS. Default: data equals
        -Value (case-insensitive). For the forcelist pass { $args[0] -like "$id;*" } so a
        row with an older update URL is recognised and updated in place.

    .PARAMETER ReservedNames
        Slot names used ELSEWHERE (another GPO, the effective machine policy) that we must
        not pick for a NEW row and must never modify.

    .PARAMETER Remove
        Take our row(s) out instead of putting one in.

    .PARAMETER KeepOnRemove
        Scriptblock ($data) -> bool, -Remove only: rows that look like ours but must stay
        (e.g. an install-source pattern another force-installed extension still needs).

    .OUTPUTS
        [pscustomobject] Slot (the name our row lands in, install only), Reused (bool),
        Ops (array of @{ Op = 'Set'|'Remove'; Name; Value }) -- the minimal diff to apply,
        and Final (the resulting name -> data map).

    .NOTES
        Install: our row lands in the LOWEST positive integer no other row uses; a row of
        ours already there is reused, any other row of ours (duplicates -- e.g. the legacy
        hashed 1000-9999 slots Deploy-PimActivatorClient.ps1 used to write) is removed.
        Every hole a removal
        opens inside a contiguous run is refilled by moving the LAST row of that run into
        it, so the org's rows after it stay visible to a reader that stops at a gap. Order
        inside these lists carries no meaning, so moving a row changes nothing else.
    #>
    [CmdletBinding()]
    param(
        [hashtable]$Existing,
        [Parameter(Mandatory)][string]$Value,
        [scriptblock]$IsOurs,
        [string[]]$ReservedNames = @(),
        [switch]$Remove,
        [scriptblock]$KeepOnRemove
    )
    $WhatIfPreference = $false   # pure builder -- never a confirmable op

    if (-not $IsOurs) { $IsOurs = New-PaRowMatcher -Exact $Value }

    # Working copy (case-insensitive names, like the registry).
    $orig = @{}
    if ($Existing) { foreach ($k in $Existing.Keys) { $orig["$k"] = "$($Existing[$k])" } }
    $work = @{}
    foreach ($k in $orig.Keys) { $work[$k] = $orig[$k] }

    $reserved = @{}
    foreach ($r in @($ReservedNames)) { if ("$r") { $reserved["$r"] = $true } }

    $ours = @($work.Keys | Where-Object { & $IsOurs $work[$_] })
    # Numeric slots first (lowest wins), then any non-numeric names, deterministically.
    $oursSorted = @($ours | Sort-Object @{ Expression = { if (Test-PaNumericSlotName $_) { [int]$_ } else { [int]::MaxValue } } }, @{ Expression = { "$_" } })

    $removed = New-Object System.Collections.Generic.List[string]
    $slot = $null; $reused = $false

    if ($Remove) {
        foreach ($n in $oursSorted) {
            if ($KeepOnRemove -and (& $KeepOnRemove $work[$n])) { continue }
            [void]$work.Remove($n); $removed.Add($n)
        }
    } else {
        # Our row belongs in the LOWEST slot not used by anybody else. If one of our
        # existing rows already sits exactly there, it is reused (idempotent re-run);
        # a row of ours stranded above a gap (e.g. the old hashed 1000-9999 slot) is
        # moved down into the documented contiguous form instead.
        $i = 1
        while (($work.ContainsKey("$i") -and -not ($oursSorted -contains "$i")) -or $reserved.ContainsKey("$i")) { $i++ }
        $slot = "$i"
        $reused = $oursSorted -contains $slot
        foreach ($n in $oursSorted) {
            if ($n -ne $slot) { [void]$work.Remove($n); $removed.Add($n) }
        }
        $work[$slot] = $Value
    }

    # Refill every hole a removal opened inside a contiguous run (see .NOTES).
    foreach ($r in @($removed | Where-Object { Test-PaNumericSlotName $_ } | Sort-Object { [int]$_ })) {
        if ($work.ContainsKey($r)) { continue }            # refilled already
        $next = [int]$r + 1
        if (-not $work.ContainsKey("$next")) { continue }   # hole at the end of a run: harmless
        $last = $next
        while ($work.ContainsKey("$($last + 1)")) { $last++ }
        $work[$r] = $work["$last"]
        [void]$work.Remove("$last")
    }

    # Minimal diff original -> work.
    $ops = New-Object System.Collections.Generic.List[object]
    foreach ($k in @($orig.Keys | Sort-Object)) {
        if (-not $work.ContainsKey($k)) { $ops.Add([pscustomobject]@{ Op = 'Remove'; Name = $k; Value = $null }) }
    }
    foreach ($k in @($work.Keys | Sort-Object)) {
        if (-not $orig.ContainsKey($k) -or $orig[$k] -cne $work[$k]) {
            $ops.Add([pscustomobject]@{ Op = 'Set'; Name = $k; Value = $work[$k] })
        }
    }
    return [pscustomobject]@{
        Slot   = $slot
        Reused = $reused
        Ops    = $ops.ToArray()
        Final  = $work
    }
}

function Get-PaExtensionSettingsPlan {
    <#
    .SYNOPSIS
        Pure. MERGE our id into the ExtensionSettings policy -- or take it out -- keeping
        every other entry the organisation has there, including the '*' defaults (BUG-182).

    .DESCRIPTION
        Chromium reads ExtensionSettings on Windows from EITHER layout:
          Value  -- a REG_SZ named 'ExtensionSettings' under the policy root holding the
                    whole dictionary as JSON (the documented form)
          Subkey -- a key named 'ExtensionSettings' with one REG_SZ per extension id
                    (value name = id or '*', data = that id's JSON)
        and when BOTH exist the subkey wins for the whole policy. So:
          * the org already uses the Subkey layout (it holds any id other than ours)
              -> add/update ONLY our value inside it; the root value is shadowed anyway.
          * otherwise -> merge our entry into the root JSON (parsed, never replaced), and
              remove a leftover subkey value of ours (the old Deploy-PimActivatorClient.ps1
              layout) so the subkey cannot shadow the merged value.
        A root value that is not a JSON object is an ERROR, not an overwrite: we will not
        replace a policy we cannot read.

    .OUTPUTS
        [pscustomobject] Layout ('Value'|'Subkey'|'None'), Error (string or $null), and Ops:
        @{ Op = 'Set'|'Remove'|'RemoveKeyIfEmpty'; Location = 'Root'|'Subkey'; Name; Value }.
        Location Root = value 'ExtensionSettings' under the policy root; Subkey = value
        <Name> under <policy root>\ExtensionSettings.
    #>
    [CmdletBinding()]
    param(
        [string]$ExistingValue,
        [hashtable]$ExistingSubkey,
        [Parameter(Mandatory)][string]$ExtensionId,
        [hashtable]$Settings,
        [switch]$Remove
    )
    $WhatIfPreference = $false   # pure builder -- never a confirmable op

    $ops = New-Object System.Collections.Generic.List[object]
    $sub = @{}
    if ($ExistingSubkey) { foreach ($k in $ExistingSubkey.Keys) { $sub["$k"] = $ExistingSubkey[$k] } }
    $foreignSub = @($sub.Keys | Where-Object { $_ -ne $ExtensionId })
    $oursInSub  = $sub.ContainsKey($ExtensionId)

    # Parse the root value (if any). $rootObj = $null means "no root value".
    $rootObj = $null; $rootErr = $null
    if ("$ExistingValue".Trim()) {
        try { $rootObj = "$ExistingValue" | ConvertFrom-Json -ErrorAction Stop } catch { $rootErr = $_.Exception.Message }
        if (-not $rootErr -and -not ($rootObj -is [System.Management.Automation.PSCustomObject])) {
            $rootErr = 'it is not a JSON object'
        }
    }

    if ($Remove) {
        if ($oursInSub) {
            $ops.Add([pscustomobject]@{ Op = 'Remove'; Location = 'Subkey'; Name = $ExtensionId; Value = $null })
            if ($foreignSub.Count -eq 0) { $ops.Add([pscustomobject]@{ Op = 'RemoveKeyIfEmpty'; Location = 'Subkey'; Name = $null; Value = $null }) }
        }
        if ($rootObj -and $rootObj.PSObject.Properties[$ExtensionId]) {
            $rootObj.PSObject.Properties.Remove($ExtensionId)
            if (@($rootObj.PSObject.Properties).Count -eq 0) {
                $ops.Add([pscustomobject]@{ Op = 'Remove'; Location = 'Root'; Name = 'ExtensionSettings'; Value = $null })
            } else {
                $ops.Add([pscustomobject]@{ Op = 'Set'; Location = 'Root'; Name = 'ExtensionSettings'; Value = (ConvertTo-Json -InputObject $rootObj -Depth 20 -Compress) })
            }
        }
        $layout = if ($ops.Count -gt 0) { if ($oursInSub) { 'Subkey' } else { 'Value' } } else { 'None' }
        # An unreadable root value on uninstall is reported, not touched.
        return [pscustomobject]@{ Layout = $layout; Error = $(if ($rootErr) { "existing ExtensionSettings value left untouched: $rootErr" } else { $null }); Ops = $ops.ToArray() }
    }

    if (-not $Settings) { throw 'Get-PaExtensionSettingsPlan: -Settings is required unless -Remove.' }
    $ourJson = ConvertTo-Json -InputObject $Settings -Depth 10 -Compress

    if ($foreignSub.Count -gt 0) {
        # The org uses the per-id subkey layout: add ours next to theirs.
        if (-not $oursInSub -or "$($sub[$ExtensionId])" -cne $ourJson) {
            $ops.Add([pscustomobject]@{ Op = 'Set'; Location = 'Subkey'; Name = $ExtensionId; Value = $ourJson })
        }
        return [pscustomobject]@{ Layout = 'Subkey'; Error = $null; Ops = $ops.ToArray() }
    }

    if ($rootErr) {
        return [pscustomobject]@{
            Layout = 'None'
            Error  = "the existing ExtensionSettings policy value cannot be merged ($rootErr). Refusing to overwrite the organisation's ExtensionSettings -- fix or remove that value, then re-run."
            Ops    = @()
        }
    }

    if ($rootObj) {
        # MERGE: keep every other entry verbatim, set/replace only ours.
        if ($rootObj.PSObject.Properties[$ExtensionId]) { $rootObj.PSObject.Properties.Remove($ExtensionId) }
        $rootObj | Add-Member -NotePropertyName $ExtensionId -NotePropertyValue $Settings -Force
        $merged = ConvertTo-Json -InputObject $rootObj -Depth 20 -Compress
    } else {
        # Nothing there: exactly what the Intune deploy writes (byte-identical).
        $merged = (@{ $ExtensionId = $Settings } | ConvertTo-Json -Depth 5 -Compress)
    }
    if ("$ExistingValue" -cne $merged) {
        $ops.Add([pscustomobject]@{ Op = 'Set'; Location = 'Root'; Name = 'ExtensionSettings'; Value = $merged })
    }
    if ($oursInSub) {
        # Legacy Deploy-PimActivatorClient.ps1 layout: a subkey holding only our id would
        # SHADOW the merged root value. Take it out.
        $ops.Add([pscustomobject]@{ Op = 'Remove'; Location = 'Subkey'; Name = $ExtensionId; Value = $null })
        $ops.Add([pscustomobject]@{ Op = 'RemoveKeyIfEmpty'; Location = 'Subkey'; Name = $null; Value = $null })
    }
    return [pscustomobject]@{ Layout = 'Value'; Error = $null; Ops = $ops.ToArray() }
}

function Read-PaPolicyRegistryState {
    <#
    .SYNOPSIS
        Read-only snapshot of the extension policies already present under one browser
        policy root (e.g. HKLM:\SOFTWARE\Policies\Microsoft\Edge). Missing keys = empty.
    .OUTPUTS
        @{ Forcelist; Sources; Allowlist = name->data hashtables; SettingsValue = string or
           $null; SettingsSubkey = name->data hashtable }
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$PolicyRoot)
    $WhatIfPreference = $false
    function Read-PaKeyValues([string]$Path) {
        $h = @{}
        if (Test-Path -LiteralPath $Path) {
            $item = Get-Item -LiteralPath $Path
            foreach ($n in @($item.GetValueNames())) { if ("$n") { $h["$n"] = "$($item.GetValue($n))" } }
        }
        return $h
    }
    $settingsValue = $null
    if (Test-Path -LiteralPath $PolicyRoot) {
        $rootItem = Get-Item -LiteralPath $PolicyRoot
        if (@($rootItem.GetValueNames()) -contains 'ExtensionSettings') { $settingsValue = "$($rootItem.GetValue('ExtensionSettings'))" }
    }
    return @{
        Forcelist      = Read-PaKeyValues (Join-Path $PolicyRoot 'ExtensionInstallForcelist')
        Sources        = Read-PaKeyValues (Join-Path $PolicyRoot 'ExtensionInstallSources')
        Allowlist      = Read-PaKeyValues (Join-Path $PolicyRoot 'ExtensionInstallAllowlist')
        SettingsValue  = $settingsValue
        SettingsSubkey = Read-PaKeyValues (Join-Path $PolicyRoot 'ExtensionSettings')
    }
}

function Invoke-PaPolicyRegistryOps {
    <#
    .SYNOPSIS
        Apply plan entries (Key relative to the hive, ValueName, ValueKind, Value, Action =
        Set|Remove|RemoveKeyIfEmpty) to a local registry hive ('HKLM:' / 'HKCU:').
        Shared by Deploy-PimActivatorClient.ps1 and Deploy-PimActivatorHybrid.ps1 -Target
        LocalGpo so both write the same layout. Returns one line per op applied.
        12.7 -WhatIf: every op goes through ShouldProcess; under -WhatIf (the caller's
        preference is inherited) nothing is written and each line reads "would ...".
    #>
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory)][string]$Hive,
        [Parameter(Mandatory)] $Entries
    )
    $done = New-Object System.Collections.Generic.List[string]
    foreach ($e in @($Entries)) {
        $path = "$Hive\$($e.Key)"
        $action = if ($e.PSObject.Properties['Action'] -and $e.Action) { $e.Action } else { 'Set' }
        switch ($action) {
            'Set' {
                $kind = if ($e.ValueKind -eq 'Dword') { 'DWord' } else { 'String' }
                if (-not $PSCmdlet.ShouldProcess("$path\$($e.ValueName)", "Set registry value ($kind)")) { $done.Add("would set    $path\$($e.ValueName)"); continue }
                if (-not (Test-Path -LiteralPath $path)) { New-Item -Path $path -Force -WhatIf:$false | Out-Null }
                New-ItemProperty -LiteralPath $path -Name $e.ValueName -Value $e.Value -PropertyType $kind -Force -WhatIf:$false | Out-Null
                $done.Add("set    $path\$($e.ValueName)")
            }
            'Remove' {
                # Remove-ItemProperty -Name takes WILDCARDS: never let a '*' (the org's
                # ExtensionSettings default entry) or '?' through as a name.
                if ("$($e.ValueName)" -match '[\*\?\[\]]') { throw "Refusing to remove registry value '$($e.ValueName)' under $path -- the name contains a wildcard character." }
                if ((Test-Path -LiteralPath $path) -and (@((Get-Item -LiteralPath $path).GetValueNames()) -contains $e.ValueName)) {
                    if (-not $PSCmdlet.ShouldProcess("$path\$($e.ValueName)", 'Remove registry value')) { $done.Add("would remove $path\$($e.ValueName)"); continue }
                    Remove-ItemProperty -LiteralPath $path -Name $e.ValueName -Force -WhatIf:$false
                    $done.Add("remove $path\$($e.ValueName)")
                }
            }
            'RemoveKeyIfEmpty' {
                if (Test-Path -LiteralPath $path) {
                    $it = Get-Item -LiteralPath $path
                    if (@($it.GetValueNames() | Where-Object { "$_" }).Count -eq 0 -and $it.SubKeyCount -eq 0) {
                        if (-not $PSCmdlet.ShouldProcess($path, 'Remove empty registry key')) { $done.Add("would remove empty key $path"); continue }
                        Remove-Item -LiteralPath $path -Force -WhatIf:$false
                        $done.Add("remove empty key $path")
                    }
                }
            }
        }
    }
    return $done.ToArray()
}

function Select-PaActivatorApp {
    <#
    .SYNOPSIS
        Pure. Pick THE PIM Activator app registration out of a Graph /applications
        result -- deterministically (BUG-220). Match by -ClientId when given, else by the
        EXACT display name; anything but exactly one match is an error, never a guess.
    .OUTPUTS
        [pscustomobject] App (the match or $null), Error (why not, or $null).
    #>
    [CmdletBinding()]
    param(
        $Apps,
        [string]$ClientId,
        [string]$DisplayName = 'PIM Activator'
    )
    $WhatIfPreference = $false
    $get = { param($o, $n) if ($o -is [System.Collections.IDictionary]) { $o[$n] } elseif ($o) { $o.$n } else { $null } }
    $all = @($Apps | Where-Object { $_ })
    if ($ClientId) {
        $m = @($all | Where-Object { "$(& $get $_ 'appId')" -ieq $ClientId })
        $what = "appId '$ClientId'"
    } else {
        $m = @($all | Where-Object { "$(& $get $_ 'displayName')" -ceq $DisplayName })
        $what = "the exact display name '$DisplayName'"
    }
    if ($m.Count -eq 1) { return [pscustomobject]@{ App = $m[0]; Error = $null } }
    if ($m.Count -eq 0) {
        return [pscustomobject]@{ App = $null; Error = "no app registration with $what (run Deploy-PimActivatorBackend.ps1, or pass -ClientId)" }
    }
    $ids = ($m | ForEach-Object { "$(& $get $_ 'appId')" }) -join ', '
    return [pscustomobject]@{ App = $null; Error = "$($m.Count) app registrations match $what ($ids) -- ambiguous; pass -ClientId <appId> to choose" }
}

function ConvertTo-PaPolicyEntries {
    <#
    .SYNOPSIS
        Turn list-plan / settings-plan ops into registry plan entries (the shape
        Get-PaHybridRegistryPlan emits and Invoke-PaPolicyRegistryOps applies).
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$Browser,
        [Parameter(Mandatory)][string]$Policy,
        [Parameter(Mandatory)][string]$PolicyKey,      # e.g. SOFTWARE\Policies\Microsoft\Edge
        [string]$ListKeyName,                          # e.g. ExtensionInstallForcelist (list ops)
        $ListOps,
        $SettingsOps
    )
    $WhatIfPreference = $false
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($o in @($ListOps)) {
        if (-not $o) { continue }
        $out.Add([pscustomobject]@{
            Browser = $Browser; Policy = $Policy; Hive = 'HKLM'
            Key = "$PolicyKey\$ListKeyName"; ValueName = "$($o.Name)"
            ValueKind = 'String'; Value = $(if ($o.Op -eq 'Set') { "$($o.Value)" } else { '' }); Action = $o.Op
        })
    }
    foreach ($o in @($SettingsOps)) {
        if (-not $o) { continue }
        $key = if ($o.Location -eq 'Subkey') { "$PolicyKey\ExtensionSettings" } else { $PolicyKey }
        $out.Add([pscustomobject]@{
            Browser = $Browser; Policy = $Policy; Hive = 'HKLM'
            Key = $key; ValueName = $(if ($o.Name) { "$($o.Name)" } else { '' })
            ValueKind = 'String'; Value = $(if ($o.Op -eq 'Set') { "$($o.Value)" } else { '' }); Action = $o.Op
        })
    }
    return $out.ToArray()
}

function Get-PaHybridRegistryPlan {
    <#
    .SYNOPSIS
        The full per-browser registry policy plan equivalent to the Intune
        client policies. Pure -- builds an in-memory plan, writes nothing.

    .PARAMETER Catalog
        Normalised tenant catalog (output of New-PaHybridConfig).

    .PARAMETER Browser
        'Both' (default), 'Edge', or 'Chrome' -- same set as the Intune deploy.

    .OUTPUTS
        [pscustomobject] with:
          CatalogJson       - the minified tenantCatalog string
          ForcelistValue    - "<extId>;<updateUrl>"
          ExtensionSettings - the ExtensionSettings JSON string
          Browsers          - the browser labels included
          Entries           - array of registry value entries, each:
              Browser   (Edge|Chrome)
              Policy    (Forcelist|Sources|Settings|Catalog)
              Hive      (always 'HKLM')
              Key       (e.g. SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist)
              ValueName (e.g. '1' for list rows, or 'ExtensionSettings'/'tenantCatalog')
              ValueKind (String|Dword)
              Value     (the data)
              Action    (Set|Remove|RemoveKeyIfEmpty)

    .PARAMETER ExistingState
        Optional. Browser label -> what is ALREADY in that browser's policy root, as
        Read-PaPolicyRegistryState returns it (+ optional ForcelistReserved /
        SourcesReserved: slot names taken elsewhere, e.g. by another GPO). With it, our
        rows go into the slot already holding our id or the lowest free one, and our
        ExtensionSettings entry is MERGED with the org's (BUG-182). Without it (the Json
        artifact) the plan assumes empty keys: slot '1', a fresh ExtensionSettings.

    .PARAMETER MinimumVersion
        Optional ExtensionSettings minimum_version_required (IMP-49 r -- was unreachable).

    .PARAMETER BulkThreshold
        Optional tenant-wide bulkActivateConfirmThreshold (1..100) written as a DWORD next
        to tenantCatalog (managed-schema.json). 0 = not written (IMP-49 r).
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] $Catalog,
        [ValidateSet('Both','Edge','Chrome')][string]$Browser = 'Both',
        [Parameter(Mandatory)][string]$ExtensionId,
        [Parameter(Mandatory)][string]$UpdateUrl,
        [Parameter(Mandatory)][string]$SourcePattern,
        [hashtable]$ExistingState,
        [string]$MinimumVersion,
        [ValidateRange(0, 100)][int]$BulkThreshold = 0,
        # Per-DEVICE auto-activate cap (2026-09-23): autoActivateMaxGroups DWORD next to tenantCatalog.
        # -1 = not written (no limit); 0 = auto-activation off; N = at most N groups.
        [ValidateRange(-1, 100)][int]$AutoActivateMaxGroups = -1,
        # ACT-ENDTIME (owner 2026-10-31): activationEndTime REG_SZ 'HH:MM' next to tenantCatalog. '' = not written.
        [ValidatePattern('^(([01][0-9]|2[0-3]):[0-5][0-9])?$')][string]$ActivationEndTime = ''
    )

    $WhatIfPreference = $false   # pure builder -- never a confirmable op

    $browsers = switch ($Browser) {
        'Both'   { @('Edge','Chrome') }
        'Edge'   { @('Edge') }
        'Chrome' { @('Chrome') }
    }

    $catalogJson  = ConvertTo-PaHybridCatalogJson -Catalog $Catalog
    $forcelistVal = New-PaHybridForcelistValue   -ExtensionId $ExtensionId -UpdateUrl $UpdateUrl
    $extSettings  = New-PaHybridExtensionSettingsJson -ExtensionId $ExtensionId -UpdateUrl $UpdateUrl -MinimumVersion $MinimumVersion
    $ourSettings  = New-PaExtensionSettingsEntry -UpdateUrl $UpdateUrl -MinimumVersion $MinimumVersion
    $isOurForcelistRow = New-PaRowMatcher -ExtensionId $ExtensionId

    $entries = New-Object System.Collections.Generic.List[object]
    $slots   = [ordered]@{}

    foreach ($b in $browsers) {
        $vendor   = $script:PaHybridVendorPath[$b]
        $polKey   = "SOFTWARE\Policies\$vendor"
        $thirdKey = "SOFTWARE\Policies\$vendor\3rdparty\extensions\$ExtensionId\policy"
        $st = if ($ExistingState -and $ExistingState.ContainsKey($b)) { $ExistingState[$b] } else { @{} }
        $stGet = { param($k) if ($st -is [System.Collections.IDictionary] -and $st.Contains($k)) { $st[$k] } else { $null } }

        # 1. ExtensionInstallForcelist -- our row in the slot holding our id, else the
        #    lowest free slot. Never a hard-coded '1' (that replaced the org's first row).
        $fl = Get-PaPolicyListPlan -Existing (& $stGet 'Forcelist') -Value $forcelistVal `
                -IsOurs $isOurForcelistRow -ReservedNames @(& $stGet 'ForcelistReserved')
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $b -Policy 'Forcelist' -PolicyKey $polKey -ListKeyName 'ExtensionInstallForcelist' -ListOps $fl.Ops)) { $entries.Add($e) }

        # 2. ExtensionInstallSources -- same rule; a row with our exact pattern is reused.
        $sr = Get-PaPolicyListPlan -Existing (& $stGet 'Sources') -Value $SourcePattern `
                -ReservedNames @(& $stGet 'SourcesReserved')
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $b -Policy 'Sources' -PolicyKey $polKey -ListKeyName 'ExtensionInstallSources' -ListOps $sr.Ops)) { $entries.Add($e) }

        # 3. ExtensionSettings -- MERGED with the org's dictionary ('*' defaults and every
        #    other extension kept). A value we cannot parse stops the plan: fail closed.
        $es = Get-PaExtensionSettingsPlan -ExistingValue (& $stGet 'SettingsValue') -ExistingSubkey (& $stGet 'SettingsSubkey') `
                -ExtensionId $ExtensionId -Settings $ourSettings
        if ($es.Error) { throw "[$b] $($es.Error)" }
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $b -Policy 'Settings' -PolicyKey $polKey -SettingsOps $es.Ops)) { $entries.Add($e) }

        # 4. tenantCatalog -- single REG_SZ JSON string under the 3rd-party
        #    extension policy path (the Intune Remediation writes here too).
        #    This key is OURS alone (it carries our extension id), so it is simply set.
        $entries.Add([pscustomobject]@{
            Browser = $b; Policy = 'Catalog'; Hive = 'HKLM'
            Key = $thirdKey; ValueName = 'tenantCatalog'
            ValueKind = 'String'; Value = $catalogJson; Action = 'Set'
        })

        # 4b. Per-tenant bulkActivateConfirmThreshold travels INSIDE tenantCatalog (per
        #     managed-schema.json). The tenant-wide DWORD is emitted only when asked for.
        if ($BulkThreshold -gt 0) {
            $entries.Add([pscustomobject]@{
                Browser = $b; Policy = 'BulkThreshold'; Hive = 'HKLM'
                Key = $thirdKey; ValueName = 'bulkActivateConfirmThreshold'
                ValueKind = 'Dword'; Value = $BulkThreshold; Action = 'Set'
            })
        }

        # 4c. Per-device auto-activate cap -- device policy only, never inside tenantCatalog.
        if ($AutoActivateMaxGroups -ge 0) {
            $entries.Add([pscustomobject]@{
                Browser = $b; Policy = 'AutoActivateMax'; Hive = 'HKLM'
                Key = $thirdKey; ValueName = 'autoActivateMaxGroups'
                ValueKind = 'Dword'; Value = $AutoActivateMaxGroups; Action = 'Set'
            })
        }

        # 4d. End-of-day time (ACT-ENDTIME) -- device policy only, never inside tenantCatalog.
        if ("$ActivationEndTime".Trim()) {
            $entries.Add([pscustomobject]@{
                Browser = $b; Policy = 'ActivationEndTime'; Hive = 'HKLM'
                Key = $thirdKey; ValueName = 'activationEndTime'
                ValueKind = 'String'; Value = "$ActivationEndTime".Trim(); Action = 'Set'
            })
        }

        $slots[$b] = [pscustomobject]@{ Forcelist = $fl.Slot; ForcelistReused = $fl.Reused; Sources = $sr.Slot; SettingsLayout = $es.Layout }
    }

    return [pscustomobject]@{
        CatalogJson       = $catalogJson
        ForcelistValue    = $forcelistVal
        ExtensionSettings = $extSettings
        Browsers          = $browsers
        Entries           = $entries.ToArray()
        Slots             = $slots
    }
}

function ConvertTo-PaHybridManagedConfigObject {
    <#
    .SYNOPSIS
        Build the -Target Json artifact: the managed-config object (per browser)
        for inspection / manual import.
    .DESCRIPTION
        Groups the registry plan into a browser-keyed object whose shape mirrors
        the effective chrome.storage.managed config + the install policies, so an
        operator can eyeball exactly what each browser will receive. This is a
        documentation/inspection artifact -- the registry plan (Get-PaHybridRegistryPlan)
        remains the single source of truth all three targets write from.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)] $Plan)

    $out = [ordered]@{}
    foreach ($b in $Plan.Browsers) {
        $managed = [ordered]@{ tenantCatalog = $Plan.CatalogJson }
        $bulk = @($Plan.Entries | Where-Object { $_.Browser -eq $b -and $_.Policy -eq 'BulkThreshold' } | Select-Object -First 1)
        if ($bulk.Count -gt 0) { $managed['bulkActivateConfirmThreshold'] = [int]$bulk[0].Value }
        $amx = @($Plan.Entries | Where-Object { $_.Browser -eq $b -and $_.Policy -eq 'AutoActivateMax' } | Select-Object -First 1)
        if ($amx.Count -gt 0) { $managed['autoActivateMaxGroups'] = [int]$amx[0].Value }
        $aet = @($Plan.Entries | Where-Object { $_.Browser -eq $b -and $_.Policy -eq 'ActivationEndTime' } | Select-Object -First 1)
        if ($aet.Count -gt 0) { $managed['activationEndTime'] = [string]$aet[0].Value }
        $out[$b] = [ordered]@{
            ExtensionInstallForcelist = @($Plan.ForcelistValue)
            ExtensionInstallSources   = @(($Plan.Entries | Where-Object { $_.Browser -eq $b -and $_.Policy -eq 'Sources' } | Select-Object -First 1).Value)
            ExtensionSettings         = $Plan.ExtensionSettings
            managedConfig             = $managed
        }
    }
    return [pscustomobject]$out
}

# ===== END inlined helper: _PimActivatorHybridPolicy.ps1 =====
} catch {
    throw "_PimActivatorHybridPolicy.ps1 was not found next to this script ($PSScriptRoot). It holds the slot + ExtensionSettings merge logic that keeps the organisation's own extension policies intact -- copy it alongside Deploy-PimActivatorClient.ps1 (or use the standalone download https://invardia.com/support/pim/Deploy-PimActivatorClient.ps1) and re-run. Nothing was written."
}

# (Matchers are built by the library, never with .GetNewClosure() -- see New-PaRowMatcher.)
$isOurForcelistRow = New-PaRowMatcher -ExtensionId $ExtensionId
$isOurAllowRow     = New-PaRowMatcher -Exact $ExtensionId

function Get-PaSourcePatternFromUrl {
    param([string]$Url)
    try {
        $u = [Uri]::new($Url)
        if ($u.Scheme -and $u.Host) { return "$($u.Scheme)://$($u.Host)/*" }
    } catch { }
    return $null
}

if ($Uninstall) {
    Write-Host "Removing PIM Activator force-install ($Scope scope, $Browser) for extension $ExtensionId..." -ForegroundColor Yellow
    Write-Host "  Only OUR rows / entries are removed; the organisation's own extension policies stay." -ForegroundColor DarkGray
    $ourSource = Get-PaSourcePatternFromUrl $UpdateUrl
    $uninstallProblems = 0

    foreach ($root in $policyRoots) {
        $state   = Read-PaPolicyRegistryState -PolicyRoot $root.Path
        $entries = New-Object System.Collections.Generic.List[object]

        # Forcelist + allowlist: every row that carries OUR id (any slot, incl. the old
        # hashed 1000-9999 ones), and the hole it leaves is refilled.
        $fl = Get-PaPolicyListPlan -Existing $state.Forcelist -Value "$ExtensionId;$UpdateUrl" -IsOurs $isOurForcelistRow -Remove
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Forcelist' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallForcelist' -ListOps $fl.Ops)) { $entries.Add($e) }
        $al = Get-PaPolicyListPlan -Existing $state.Allowlist -Value $ExtensionId -IsOurs $isOurAllowRow -Remove
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Allowlist' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallAllowlist' -ListOps $al.Ops)) { $entries.Add($e) }

        # Install source: a pattern is not id-tagged, so it is removed only when no
        # REMAINING forcelist row still installs from that host (the test channel, or
        # the org's own extension served from the same site).
        if ($ourSource) {
            $stillNeeded = @($fl.Final.Values | Where-Object {
                $u = ("$_" -split ';', 2)[1]
                $u -and ((Get-PaSourcePatternFromUrl $u) -ieq $ourSource)
            }).Count -gt 0
            $keep = if ($stillNeeded) { { $true } } else { $null }
            $sr = Get-PaPolicyListPlan -Existing $state.Sources -Value $ourSource -Remove -KeepOnRemove $keep
            foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Sources' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallSources' -ListOps $sr.Ops)) { $entries.Add($e) }
            if ($stillNeeded) { Write-Host "  [$($root.Name)] install source $ourSource kept -- another forcelist row still installs from it" -ForegroundColor DarkGray }
        }

        # ExtensionSettings: take OUR id out of the dictionary / per-id key only.
        $es = Get-PaExtensionSettingsPlan -ExistingValue $state.SettingsValue -ExistingSubkey $state.SettingsSubkey -ExtensionId $ExtensionId -Remove
        if ($es.Error) { Write-Warning "  [$($root.Name)] $($es.Error)"; $uninstallProblems++ }
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Settings' -PolicyKey $root.Rel -SettingsOps $es.Ops)) { $entries.Add($e) }

        foreach ($line in @(Invoke-PaPolicyRegistryOps -Hive $hiveRoot -Entries $entries.ToArray())) {
            Write-Host "  [$($root.Name)] $line" -ForegroundColor DarkGray
        }

        # The 3rdparty\extensions\<id> tree (tenantCatalog) is keyed by OUR id -- all ours.
        $catalogRoot = Join-Path $root.Path "3rdparty\extensions\$ExtensionId"
        if ((Test-Path -LiteralPath $catalogRoot) -and $PSCmdlet.ShouldProcess($catalogRoot, 'Remove the registry key (tenant catalog + per-device settings of this extension)')) {
            Remove-Item -LiteralPath $catalogRoot -Recurse -Force -ErrorAction SilentlyContinue -WhatIf:$false
            Write-Host "  [$($root.Name)] removed 3rdparty\extensions\$ExtensionId" -ForegroundColor DarkGray
        }
    }

    if ($uninstallProblems -gt 0) {
        Write-Warning "Uninstall finished with $uninstallProblems ExtensionSettings value(s) left untouched (see above) -- remove the '$ExtensionId' entry from them by hand."
        exit 1
    }
    if ($_preview) { Write-Host 'PREVIEW (-WhatIf) complete: nothing was removed. Run the same command without -WhatIf to apply.' -ForegroundColor Yellow; return }
    Write-Host "Done. Restart $Browser to apply." -ForegroundColor Green
    return
}

# ---------------------------------------------------------------------------
# Install
# ---------------------------------------------------------------------------

if ($Scope -eq 'Machine') {
    Write-Host ""
    Write-Host "  -Scope Machine (default) -- writing to HKLM, applies to every user on this box." -ForegroundColor Cyan
    Write-Host "  Note: on Intune-managed devices, the Intune-pushed ExtensionInstallForcelist will" -ForegroundColor DarkGray
    Write-Host "        overwrite this on next sync -- use the Edge management service + the Intune Remediation there (README.md)." -ForegroundColor DarkGray
    Write-Host ""
} else {
    Write-Host ""
    Write-Host "  -Scope User selected -- HKCU-only. Won't affect other users or Intune." -ForegroundColor Green
    Write-Host ""
}

Write-Host "Installing PIM Activator force-install policy ($Scope scope, $Browser)..." -ForegroundColor Cyan
# Only echo ExtensionId / UpdateUrl when the operator explicitly overrode the
# baked-in defaults. v2.4.57 made both defaultable so a zero-arg invocation
# Just Works -- noise in the output (and the operator wondering "did I have
# to pass that?") is a downgrade.
$_defaultExtId  = 'eheocihmlppcophaeakmdenhgcookkab'
$_defaultUpdUrl = 'https://knudsenmorten.github.io/PIM4EntraPS/updates.xml'
if ($ExtensionId -ne $_defaultExtId)  { Write-Host "  ExtensionId : $ExtensionId  (overridden -- default is $_defaultExtId)" -ForegroundColor Yellow }
if ($UpdateUrl   -ne $_defaultUpdUrl) { Write-Host "  UpdateUrl   : $UpdateUrl  (overridden -- default is $_defaultUpdUrl)" -ForegroundColor Yellow }

# Derive the source-host pattern from the update URL so a customer who
# self-hosts the CRX (different update.xml host) gets the right allow
# pattern instead of a stale knudsenmorten.github.io one. $null (unparseable)
# => ExtensionInstallSources is skipped.
$sourcePattern = Get-PaSourcePatternFromUrl $UpdateUrl

# ---- Plan EVERY browser's policy writes first, write nothing until all are known ----
# A plan that cannot be made safely (an ExtensionSettings value we cannot parse) stops
# the run BEFORE any browser is touched -- fail closed, never a half-applied policy.
$ourSettings = New-PaExtensionSettingsEntry -UpdateUrl $UpdateUrl
$policyPlans = @{}
foreach ($root in $policyRoots) {
    $state   = Read-PaPolicyRegistryState -PolicyRoot $root.Path
    $entries = New-Object System.Collections.Generic.List[object]
    $notes   = New-Object System.Collections.Generic.List[string]

    # 1. ExtensionInstallForcelist -- "<extension-id>;<update-url>" in the slot that
    #    already holds our id (reused, any stray duplicates removed), else the lowest
    #    free slot. The org's rows are never overwritten.
    $fl = Get-PaPolicyListPlan -Existing $state.Forcelist -Value "$ExtensionId;$UpdateUrl" -IsOurs $isOurForcelistRow
    foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Forcelist' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallForcelist' -ListOps $fl.Ops)) { $entries.Add($e) }
    $notes.Add("ExtensionInstallForcelist slot $($fl.Slot) $(if ($fl.Reused) { '(reused -- already held our id)' } else { '(lowest free slot)' }) = $ExtensionId;$UpdateUrl")

    # 2. ExtensionInstallAllowlist -- OPT-IN ONLY (-WriteAllowlist).
    #
    # 2026-06-10: this used to be written by default as "belt and braces"
    # in case the admin had ExtensionInstallBlocklist='*'. In practice it
    # backfired -- on some Chromium versions an Allowlist with ONLY one
    # id is interpreted as "deny every other extension" even without a
    # '*' blocklist in play. Symptom: users couldn't install any other
    # extension. Forcelist already overrides the blocklist for our id,
    # so the Allowlist write was redundant. Now only written when the
    # operator explicitly opts in for an environment that DOES set a
    # '*' blocklist.
    if ($WriteAllowlist) {
        $al = Get-PaPolicyListPlan -Existing $state.Allowlist -Value $ExtensionId -IsOurs $isOurAllowRow
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Allowlist' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallAllowlist' -ListOps $al.Ops)) { $entries.Add($e) }
        $notes.Add("ExtensionInstallAllowlist slot $($al.Slot) = $ExtensionId  [opt-in, -WriteAllowlist]")
    }

    # 3. ExtensionInstallSources -- allow the host the CRX + updates.xml are served
    #    from. Required if the admin has restricted ExtensionInstallSources (some
    #    hardened baselines do). A row with exactly our pattern is reused.
    if ($sourcePattern) {
        $sr = Get-PaPolicyListPlan -Existing $state.Sources -Value $sourcePattern
        foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Sources' -PolicyKey $root.Rel -ListKeyName 'ExtensionInstallSources' -ListOps $sr.Ops)) { $entries.Add($e) }
        $notes.Add("ExtensionInstallSources slot $($sr.Slot) = $sourcePattern")
    }

    # 4. ExtensionSettings -- our entry pre-grants runtime_allowed_hosts for THIS
    #    extension only (the 2026-06-10 fleet-freeze fix: an auto-update that looked
    #    like a permission expansion was silently disabled; the policy-level grant
    #    stops that gate firing). It is MERGED into the org's ExtensionSettings --
    #    their '*' defaults and other extensions' entries are kept (BUG-182).
    #    Layout: the documented single REG_SZ 'ExtensionSettings' JSON under the policy
    #    root, UNLESS the org already uses the per-id key layout (<root>\ExtensionSettings
    #    with one value per id), in which case our value is added next to theirs. A
    #    per-id key holding only OUR id (what this script used to write) is removed,
    #    because Chromium lets that key shadow the whole root value.
    $es = Get-PaExtensionSettingsPlan -ExistingValue $state.SettingsValue -ExistingSubkey $state.SettingsSubkey -ExtensionId $ExtensionId -Settings $ourSettings
    if ($es.Error) { throw "[$($root.Name)] $($es.Error)" }
    foreach ($e in (ConvertTo-PaPolicyEntries -Browser $root.Name -Policy 'Settings' -PolicyKey $root.Rel -SettingsOps $es.Ops)) { $entries.Add($e) }
    $notes.Add("ExtensionSettings: our entry $(if ($es.Layout -eq 'Subkey') { "added to the org's per-id ExtensionSettings key" } else { 'merged into the ExtensionSettings dictionary' }) (runtime_allowed_hosts = <all_urls>)")

    $policyPlans[$root.Name] = [pscustomobject]@{ Entries = $entries.ToArray(); Notes = $notes.ToArray() }
}
$catalogMissing = New-Object System.Collections.Generic.List[string]

foreach ($root in $policyRoots) {
    Write-Host ""
    Write-Host "  [$($root.Name)] writing under $($root.Path)" -ForegroundColor Cyan

    $pp = $policyPlans[$root.Name]
    foreach ($line in @(Invoke-PaPolicyRegistryOps -Hive $hiveRoot -Entries $pp.Entries)) {
        Write-Host "    -> $line" -ForegroundColor DarkGray
    }
    foreach ($n in $pp.Notes) { Write-Host "    -> $n" -ForegroundColor DarkGray }

    # 5. Tenant catalog (chrome.storage.managed.tenantCatalog).
    #
    # On Intune-managed boxes the catalog arrives through the Intune Remediation
    # template (Group Policy CSP), surfacing under chrome.storage.managed
    # so the popup's 'Use centrally deployed' tile turns active. On
    # non-Intune boxes the same data path -- the chrome.storage.managed
    # registry namespace -- is directly writable from an admin shell:
    #
    #   <policy-root>\3rdparty\extensions\<EXT_ID>\policy\
    #     tenantCatalog (REG_SZ) = minified JSON array of tenant entries
    #
    # The extension reads chrome.storage.managed.tenantCatalog at popup
    # open time. Same effect as the Intune Remediation, just locally pushed.
    # Skipped when -SkipTenantCatalog OR when the JSON file isn't present.
    if ($SkipTenantCatalog) {
        Write-Host "    -> tenantCatalog skipped (-SkipTenantCatalog)" -ForegroundColor DarkGray
    } else {
        # Resolve the catalog object: explicit file > live Entra auto-discover.
        # No more silent fallback to a sibling 'discovered-tenant-catalog.json' --
        # see v2.4.111 release notes for the cross-tenant-leak incident.
        $catalog = $null
        if ($CatalogJsonPath -and (Test-Path -LiteralPath $CatalogJsonPath)) {
            try {
                $catalogRaw = Get-Content -LiteralPath $CatalogJsonPath -Raw -Encoding UTF8
                $catalog    = $catalogRaw | ConvertFrom-Json
                Write-Host "    -> catalog source: -CatalogJsonPath '$CatalogJsonPath'" -ForegroundColor DarkGray
            } catch {
                Write-Warning "    -CatalogJsonPath parse failed: $($_.Exception.Message). Will try live Entra auto-discover instead."
                $catalog = $null
            }
        } elseif ($CatalogJsonPath) {
            Write-Warning "    -CatalogJsonPath '$CatalogJsonPath' not found. Falling back to live Entra auto-discover."
        }

        # 97.2: -TenantId + -ClientId given -> the catalog from these values, no sign-in, no file.
        if (-not $catalog -and $TenantId -and $ClientId) {
            $catalog = [pscustomobject]@{
                name                 = $(if ("$TenantName".Trim()) { "$TenantName".Trim() } else { 'PIM' })
                tenantId             = $TenantId.ToLowerInvariant()
                clientId             = $ClientId.ToLowerInvariant()
                defaultJustification = $(if ($PSBoundParameters.ContainsKey('DefaultJustification')) { $DefaultJustification } else { 'Change in infrastructure' })
                defaultDurationHours = $(if ($PSBoundParameters.ContainsKey('DefaultDurationHours')) { $DefaultDurationHours } else { 8 })
            }
            # the optional name filters, the same keys the Remediation's catalog carries
            if ("$Prefix".Trim())      { $catalog | Add-Member -NotePropertyName prefix -NotePropertyValue "$Prefix".Trim() }
            if ("$EntraPrefix".Trim()) { $catalog | Add-Member -NotePropertyName entraPrefix -NotePropertyValue "$EntraPrefix".Trim() }
            if ("$AzurePrefix".Trim()) { $catalog | Add-Member -NotePropertyName azurePrefix -NotePropertyValue "$AzurePrefix".Trim() }
            # the defaults went into THIS tenant's entry; the extra tenants keep their own (no override below)
            $catFromParams = $true
            Write-Host ("    -> catalog source: -TenantId / -ClientId (tenant '{0}' / {1}  clientId {2})" -f $catalog.name, $catalog.tenantId, $catalog.clientId) -ForegroundColor Cyan
            if ("$AdditionalTenantsJson".Trim()) {
                # the same rules the PIM Manager page and the Remediation apply (name + tenantId + clientId, known keys only)
                $guidRx = '^[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}$'
                $xtParsed = $null; try { $xtParsed = ConvertFrom-Json -InputObject $AdditionalTenantsJson } catch { throw "-AdditionalTenantsJson is not valid JSON: $($_.Exception.Message)" }
                $xt = @($xtParsed)
                foreach ($x in $xt) {
                    if ("$($x.tenantId)" -notmatch $guidRx -or "$($x.clientId)" -notmatch $guidRx -or -not "$($x.name)".Trim()) { throw "-AdditionalTenantsJson: every tenant needs name, tenantId and clientId (GUIDs)." }
                }
                $catalog = @($catalog) + $xt
                Write-Host "    -> plus $($xt.Count) more tenant(s) from -AdditionalTenantsJson" -ForegroundColor Cyan
            }
        }

        if (-not $catalog) {
            # Live auto-discover from the connected Microsoft Graph context.
            # The same discover logic as before, so the same
            # catalog ends up in registry for non-Intune-managed boxes.
            # Plain REST with a browser sign-in (auth code + PKCE, Microsoft Graph Command Line Tools public client) -- no module.
            if (-not (Get-Command Get-PaInteractiveToken -ErrorAction SilentlyContinue)) {
                Write-Warning "    the sign-in helper (_PimActivatorAuth.ps1) is not next to this script; tenantCatalog skipped. Pass -CatalogJsonPath, or download the standalone script from https://invardia.com/support/pim/Deploy-PimActivatorClient.ps1"
            } else {
                $gTok = $null
                Write-Host "    -> signing in to Microsoft Graph (browser) to auto-discover tenant + PIM Activator app..." -ForegroundColor Cyan
                try { $gTok = "$((Get-PaInteractiveToken -Scopes @('Organization.Read.All', 'Application.Read.All')).access_token)" } catch { Write-Warning "    Sign-in failed: $($_.Exception.Message). tenantCatalog skipped."; $gTok = $null }
                $gH = @{ Authorization = "Bearer $gTok" }
                if ($gTok) {
                    try {
                        $orgResp = Invoke-RestMethod -Method GET -Uri 'https://graph.microsoft.com/v1.0/organization' -Headers $gH -ErrorAction Stop
                        $org = @($orgResp.value)[0]
                        # BUG-220: select the app DETERMINISTICALLY -- by -ClientId, else by
                        # EXACT display name, and refuse when that is not unique. It used to
                        # take the first app whose name merely STARTS WITH 'PIM Activator'
                        # (Graph returns no guaranteed order), so a tenant holding e.g. a
                        # 'PIM Activator (old)' registration could get the wrong clientId
                        # baked into every admin's browser.
                        $appFilter = if ($ClientId) { "appId eq '$ClientId'" } else { "displayName eq '$($AppDisplayName -replace "'", "''")'" }
                        $appResp = Invoke-RestMethod -Method GET -Uri ("https://graph.microsoft.com/v1.0/applications?`$filter={0}&`$select=appId,displayName" -f [uri]::EscapeDataString($appFilter)) -Headers $gH -ErrorAction Stop
                        $pick = Select-PaActivatorApp -Apps @($appResp.value) -ClientId $ClientId -DisplayName $AppDisplayName
                        $app = $pick.App
                        if (-not $org -or -not $app) {
                            $why = if (-not $org) { 'the organization could not be read' } else { $pick.Error }
                            Write-Warning "    Live Entra auto-discover incomplete: $why. tenantCatalog skipped."
                        } else {
                            $catalog = [pscustomobject]@{
                                name                  = $org.displayName
                                tenantId              = $org.id
                                clientId              = $app.appId
                                defaultJustification  = 'Change in infrastructure'
                                defaultDurationHours  = 8
                            }
                            Write-Host ("    -> catalog source: live Entra auto-discover  (tenant '{0}' / {1}  clientId {2})" -f $org.displayName, $org.id, $app.appId) -ForegroundColor Cyan
                        }
                    } catch {
                        Write-Warning "    Live Entra auto-discover failed: $($_.Exception.Message). tenantCatalog skipped."
                    }
                }
            }
        }

        # Apply explicit activation-default overrides (-DefaultJustification /
        # -DefaultDurationHours) onto every resolved tenant entry, whether the
        # catalog came from -CatalogJsonPath or live auto-discover. The popup
        # reads these from chrome.storage.managed.tenantCatalog and pre-fills
        # the Activate form with them. Add-Member -Force overwrites the property
        # if the entry already carried one. Opt-in: untouched unless passed.
        if ($catalog -and -not $catFromParams -and ($PSBoundParameters.ContainsKey('DefaultJustification') -or $PSBoundParameters.ContainsKey('DefaultDurationHours'))) {
            foreach ($entry in @($catalog)) {
                if ($PSBoundParameters.ContainsKey('DefaultJustification')) {
                    $entry | Add-Member -NotePropertyName defaultJustification -NotePropertyValue $DefaultJustification -Force
                }
                if ($PSBoundParameters.ContainsKey('DefaultDurationHours')) {
                    $entry | Add-Member -NotePropertyName defaultDurationHours -NotePropertyValue $DefaultDurationHours -Force
                }
            }
            $_ovr = @()
            if ($PSBoundParameters.ContainsKey('DefaultJustification')) { $_ovr += "justification='$DefaultJustification'" }
            if ($PSBoundParameters.ContainsKey('DefaultDurationHours'))  { $_ovr += "duration=${DefaultDurationHours}h" }
            Write-Host ("    -> activation defaults overridden on all $(@($catalog).Count) entr$(if(@($catalog).Count -eq 1){'y'}else{'ies'}): $($_ovr -join ', ')") -ForegroundColor DarkGray
        }

        if ($catalog) {
            try {
                # PS 5.1 unwraps single-element arrays during pipeline -- use
                # InputObject + @($catalog) so the JSON keeps its [ ] brackets
                # whether the catalog has 1 or many tenants.
                $catalogMin = ConvertTo-Json -InputObject @($catalog) -Depth 10 -Compress
                $catalogKey = Join-Path $root.Path "3rdparty\extensions\$ExtensionId\policy"
                $tenantCount = @($catalog).Count
                if ($PSCmdlet.ShouldProcess("$catalogKey\tenantCatalog", "Set registry value (String): the tenant catalog, $tenantCount tenant(s) -- $catalogMin")) {
                    New-PolicyKey -Path $catalogKey
                    Set-Reg -Path $catalogKey -Name 'tenantCatalog' -Value $catalogMin
                    Write-Host "    -> tenantCatalog written ($tenantCount tenant(s)) under 3rdparty\extensions\$ExtensionId\policy" -ForegroundColor DarkGray
                } else {
                    Write-Host "    -> would write tenantCatalog ($tenantCount tenant(s)) under 3rdparty\extensions\$ExtensionId\policy" -ForegroundColor Yellow
                }
            } catch {
                Write-Warning "    Tenant catalog write failed: $($_.Exception.Message). Other policies were still written."
                $catalogMissing.Add($root.Name)
            }
        } else {
            $catalogMissing.Add($root.Name)
        }
    }

    # Per-DEVICE limits: the auto-activate cap (2026-09-23) and the bulk confirm threshold (2026-10-22). Written
    # independently of the catalog, so they also apply with -SkipTenantCatalog, and for BOTH PIM Activator extensions
    # (production and test behave the same -- the Intune Remediation does the same). Not passed = this device's current
    # value is left alone; a number = written as REG_DWORD; -1 = removed.
    $limits = @()
    if ($PSBoundParameters.ContainsKey('AutoActivateMaxGroups')) {
        $limits += ,@('autoActivateMaxGroups', $AutoActivateMaxGroups, $(if ($AutoActivateMaxGroups -eq 0) { 'auto-activation OFF' } elseif ($AutoActivateMaxGroups -gt 0) { "at most $AutoActivateMaxGroups group(s)" } else { 'no limit' }))
    }
    if ($PSBoundParameters.ContainsKey('BulkActivateConfirmThreshold')) {
        if ($BulkActivateConfirmThreshold -eq 0) { throw '-BulkActivateConfirmThreshold must be 1-100, or -1 to remove it.' }
        $limits += ,@('bulkActivateConfirmThreshold', $BulkActivateConfirmThreshold, $(if ($BulkActivateConfirmThreshold -gt 0) { "confirm from $BulkActivateConfirmThreshold item(s)" } else { 'the extension default' }))
    }
    foreach ($limitId in @(@($ExtensionId) + $limitExtensionIds | Select-Object -Unique)) {
        $lKey = Join-Path $root.Path "3rdparty\extensions\$limitId\policy"
        foreach ($l in $limits) {
            $lName = $l[0]; $lVal = [int]$l[1]; $lTxt = $l[2]
            if (-not $PSCmdlet.ShouldProcess("$lKey\$lName", $(if ($lVal -ge 0) { "Set registry value (DWord) = $lVal ($lTxt)" } else { "Remove registry value ($lTxt)" }))) {
                Write-Host "    -> would $(if ($lVal -ge 0) { "set $lName = $lVal ($lTxt)" } else { "remove $lName ($lTxt)" }) under 3rdparty\extensions\$limitId\policy" -ForegroundColor Yellow
            } elseif ($lVal -ge 0) {
                Set-Reg -Path $lKey -Name $lName -Value $lVal -Kind DWord
                Write-Host "    -> $lName = $lVal ($lTxt) under 3rdparty\extensions\$limitId\policy" -ForegroundColor DarkGray
            } else {
                if (Test-Path -LiteralPath $lKey) { Remove-ItemProperty -LiteralPath $lKey -Name $lName -ErrorAction SilentlyContinue -WhatIf:$false }
                Write-Host "    -> $lName removed ($lTxt) under 3rdparty\extensions\$limitId\policy" -ForegroundColor DarkGray
            }
        }
        # ACT-ENDTIME: the end-of-day time (REG_SZ), same keys as the limits above
        if ($PSBoundParameters.ContainsKey('ActivationEndTime')) {
            $eVal = "$ActivationEndTime".Trim()
            if (-not $PSCmdlet.ShouldProcess("$lKey\activationEndTime", $(if ($eVal -ne 'none') { "Set registry value (String) = $eVal (activations end no later than $eVal)" } else { 'Remove registry value (no end time)' }))) {
                Write-Host "    -> would $(if ($eVal -ne 'none') { "set activationEndTime = $eVal" } else { 'remove activationEndTime' }) under 3rdparty\extensions\$limitId\policy" -ForegroundColor Yellow
            } elseif ($eVal -ne 'none') {
                Set-Reg -Path $lKey -Name 'activationEndTime' -Value $eVal -Kind String
                Write-Host "    -> activationEndTime = $eVal under 3rdparty\extensions\$limitId\policy" -ForegroundColor DarkGray
            } else {
                if (Test-Path -LiteralPath $lKey) { Remove-ItemProperty -LiteralPath $lKey -Name 'activationEndTime' -ErrorAction SilentlyContinue -WhatIf:$false }
                Write-Host "    -> activationEndTime removed (no end time) under 3rdparty\extensions\$limitId\policy" -ForegroundColor DarkGray
            }
        }
    }
}

# Fail LOUD, never a quiet success: the catalog was asked for (no -SkipTenantCatalog)
# but not written, so the extension installs with no tenant to sign in to.
if ($catalogMissing.Count -gt 0) {
    Write-Host ""
    Write-Host ("INCOMPLETE: the force-install policies were written, but the tenant catalog was NOT written for {0} (see the warnings above). Fix the cause and re-run, pass -CatalogJsonPath / -ClientId, or pass -SkipTenantCatalog if the catalog is delivered another way." -f ($catalogMissing -join ', ')) -ForegroundColor Red
    exit 1
}

Write-Host ""
if ($_preview) {
    Write-Host 'PREVIEW (-WhatIf) complete: nothing was written. Run the same command without -WhatIf (elevated for -Scope Machine) to apply.' -ForegroundColor Yellow
    return
}
Write-Host "Done. Restart $Browser (or wait for next launch) to apply policy." -ForegroundColor Green
Write-Host ""
Write-Host "First-run user experience:" -ForegroundColor Yellow
Write-Host "  1. Browser auto-installs the extension on next launch."
Write-Host "  2. User clicks the PIM Activator icon -> setup wizard appears."
Write-Host "  3. User picks 'Use centrally deployed' (the tenant catalog written above) and"
$_jdefault = if ($PSBoundParameters.ContainsKey('DefaultJustification')) { $DefaultJustification } else { 'Change in infrastructure' }
$_ddefault = if ($PSBoundParameters.ContainsKey('DefaultDurationHours'))  { "$DefaultDurationHours" } else { '8' }
Write-Host "     signs in once -> defaults pre-filled ($_jdefault / ${_ddefault}h)."
Write-Host "  4. Activate / My Access tabs are live. Sign-in lasts for the browser session."
if ($Browser -in @('Edge','Both'))   { Write-Host "Validate force-install: edge://policy   -> search 'ExtensionInstallForcelist' / extension id." -ForegroundColor DarkGray }
if ($Browser -in @('Chrome','Both')) { Write-Host "Validate force-install: chrome://policy -> search 'ExtensionInstallForcelist' / extension id." -ForegroundColor DarkGray }
} finally { Stop-PimScriptRun -Script 'Deploy-PimActivatorClient' }