#Requires -Version 5.1
# PIM Manager 3.0.70 -- Initialize-PimHybridWorkerAd.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: ..\setup\_pimscriptdoc.ps1)


<#
.SYNOPSIS
    §80.2 PIMHYBRIDWRK -- the Active Directory half of the hybrid worker: its gMSA identities, the rights they need, the
    servers GPO, and (optionally) an offline domain-join blob for the worker VM.

.DESCRIPTION
    Prepares Active Directory for the PIM for Active Directory hybrid worker: its group managed service accounts, their
    least-privilege rights, the servers GPO and, for an Azure VM, the offline domain-join blob.

    Run on a domain controller, or on any domain-joined host, as an account with rights to create gMSAs, groups, GPOs
    and OU permissions. No ActiveDirectory PowerShell module: directory reads/writes are LDAP via .NET
    (System.DirectoryServices); dsacls.exe sets the OU rights. Two in-box modules remain, each behind one rare step
    (REQ 100.42, both under the owner's exception of 2026-10-09 for on-prem AD / GroupPolicy on the hybrid worker):
    GroupPolicy only to CREATE the servers GPO the first time, and Kds only behind the opt-in -CreateKdsRootKey. Every
    step is read-before-write and idempotent; -WhatIf prints the plan and changes nothing.

    IDENTITY DESIGN (operator 2026-09-30 -- the pattern the domain's other automation identities already follow):
      every identity is THREE objects in -GmsaOu
        <name>                          the gMSA, named gMSA-<code>-L<level>-T<tier>
        <name>-PermissionGroup          the gMSA is its only member; EVERY right is granted to this group, never to the account
        <name>-PrincipalsAllowedAccess  the computers allowed to retrieve the gMSA's password (the worker VM)
      and ONE identity per privilege tier:
        -GmsaName        (default gMSA-PIM-L1-T0) AD groups + just-in-time membership + admin accounts. Tier 0: protected
                         groups (Domain / Enterprise / Schema Admins nesting) are reached through AdminSDHolder.
        -ServerGmsaName  (e.g.    gMSA-PIM-L2-T1) server onboarding: its PermissionGroup is put into the servers' local
                         Administrators by the -ServerOu GPO, and the worker sets each server's local Administrators as it.

      1. KDS root key       -- required for any gMSA. Refused when missing unless -CreateKdsRootKey (a forest-wide object).
      2. Worker computer    -- -ProvisionOdj: `djoin /provision` creates the computer account in -ComputerOu and prints the
                               one-time join blob between the markers ODJ-BLOB-BEGIN / ODJ-BLOB-END.
      3. Identities         -- the three objects above, for -GmsaName and (when given) -ServerGmsaName. AES256 only.
      4. Rights             -- on <GmsaName>-PermissionGroup, least privilege per OU:
                               -GroupsOu        create groups; write member / displayName / description on its groups
                               -AllowGroupCleanup: also delete group objects in -GroupsOu -- needed only for the reviewed
                                                clean-up of old PIM groups (a SuperAdmin approves the exact list in PIM
                                                Manager; without this right an approved deletion is reported as refused).
                               -AdminAccountsOu create users; full control of the user objects BELOW that OU
                               -GrantProtectedGroupMembership: write 'member' on AdminSDHolder (adminCount=1 groups: SDProp
                                                replaces their ACL hourly, so an OU grant never reaches them).
                                                ⚠️ Whoever controls that gMSA is then TIER 0. Treat the worker VM as a DC.
      5. Servers GPO        -- -ServerOu: a GPO (-ServerAdminGpoName) with Restricted Groups "member of": the server
                               identity's PermissionGroup joins BUILTIN\Administrators on every computer below the OU --
                               ADDED, nothing removed. Linked to each -ServerOu.

    What it deliberately does NOT do:
      * enable the AD Privileged Access Management feature -- irreversible for the forest. It is DETECTED and reported.
      * put an identity into a PIM just-in-time group: those groups' members are the people with an active elevation, and
        the PIM-for-AD sync removes anyone else (it removed the first worker gMSA from the shared server-admins group).
      * grant anything on protected USER accounts (adminCount=1).

.EXAMPLE
    .\Initialize-PimHybridWorkerAd.ps1 -WorkerComputerName PIMHYBRIDWRK -ComputerOu 'OU=Servers,DC=corp,DC=local' `
        -GmsaOu 'OU=Automation,OU=Service Accounts,DC=corp,DC=local' -GroupsOu 'OU=PIM Groups,DC=corp,DC=local' `
        -AdminAccountsOu 'OU=Admin Accounts,DC=corp,DC=local' -GrantProtectedGroupMembership `
        -ServerGmsaName gMSA-PIM-L2-T1 -ServerOu 'OU=Servers,DC=corp,DC=local' -WhatIf

.NOTES
    Requirements:
      PowerShell: Windows PowerShell 5.1 (powershell.exe) on a domain controller or a domain-joined Windows server --
                  one of PIM's three exceptions to PowerShell 7. Why: it uses the Windows GroupPolicy module (to create
                  the servers GPO) and Add-KdsRootKey (with -CreateKdsRootKey), which are Windows PowerShell modules.
      Role: Domain Admins (Active Directory); Enterprise Admins only with -CreateKdsRootKey. No Microsoft Entra or
            Azure role.
      Hosts: the domain controllers only (LDAP, SYSVOL); no internet.

    PERMISSIONS AND CHANGES (from Initialize-PimHybridWorkerAd.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Initialize-PimHybridWorkerAd/)
    The person running it needs:
      - Domain Admins [other, the domain] -- creates gMSAs, groups and the servers GPO, and delegates OU rights (dsacls)
      - Enterprise Admins (only with -CreateKdsRootKey) [other, the forest] -- creates the forest's KDS root key
    What it creates, changes or grants:
      - create per identity: the gMSA (AES256), <name>-PermissionGroup (the gMSA its only member) and <name>-PrincipalsAllowedAccess (the worker computer) (Active Directory (-GmsaOu)) -- AD is written only by gMSAs, one per privilege tier; every right goes to the PermissionGroup Undo: delete the gMSAs and their two groups
      - update ACEs for <GmsaName>-PermissionGroup: -GroupsOu read + create groups + write member/displayName/description (+ delete groups only with -AllowGroupCleanup); each -AdminAccountsOu create users + full control below; AdminSDHolder write member only with -GrantProtectedGroupMembership (Tier 0) (Active Directory OUs) -- least privilege per OU Undo: dsacls <dn> /R <DOMAIN>\<GmsaName>-PermissionGroup
      - create a GPO (Restricted Groups: <ServerGmsaName>-PermissionGroup member of BUILTIN\Administrators, adds only) linked to each -ServerOu (Group Policy (only with -ServerGmsaName + -ServerOu)) -- server onboarding by the Tier-1 identity Undo: unlink and delete the GPO
      - create the worker's computer account in -ComputerOu and the offline domain-join blob (printed) (Active Directory (-ProvisionOdj, Azure VM)) -- joins the Azure VM without line of sight; an Azure Arc server is already joined Undo: delete the computer account
      - create a KDS root key (Add-KdsRootKey), usable about 10 hours later (the forest (-CreateKdsRootKey)) -- no gMSA exists without one Undo: none (forest-wide; leave it)
    -WhatIf: Prints every object, right, GPO setting and link it would create; creates nothing.
    Undo: Unlink and delete the servers GPO, remove the ACEs (dsacls <dn> /R <DOMAIN>\<GmsaName>-PermissionGroup) on -GroupsOu, each -AdminAccountsOu and AdminSDHolder, then delete the gMSAs, their groups and (for an Azure VM) the computer account.

.LINK
    https://invardia.com/docs/pim/scripts/Initialize-PimHybridWorkerAd/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][ValidatePattern('^[A-Za-z0-9-]{1,15}$')][string]$WorkerComputerName,
    [Parameter(Mandatory)][string]$ComputerOu,
    [ValidatePattern('^[A-Za-z0-9-]{1,15}$')][string]$GmsaName = 'gMSA-PIM-L1-T0',
    [Parameter(Mandatory)][string]$GmsaOu,
    [Parameter(Mandatory)][string]$GroupsOu,
    [string[]]$AdminAccountsOu = @(),
    [switch]$GrantProtectedGroupMembership,
    # PIM 100.123: the reviewed clean-up of old PIM groups -- the worker may DELETE group objects in -GroupsOu (opt-in)
    [switch]$AllowGroupCleanup,
    # server onboarding, tier-split: its own identity + the GPO that makes its PermissionGroup local admin on -ServerOu
    [ValidatePattern('^$|^[A-Za-z0-9-]{1,15}$')][string]$ServerGmsaName = '',
    [string[]]$ServerOu = @(),
    [string]$ServerAdminGpoName = '',
    [string]$UsedBy = 'PIM Manager hybrid worker',
    [switch]$ProvisionOdj,
    [switch]$ReuseComputer,
    [switch]$CreateKdsRootKey,
    [switch]$TriggerSdProp
)
$ErrorActionPreference = 'Stop'

# 12.7 run frame: "<Script> version <x.y.z> - documentation: <page>" as the first line + a transcript in the temp folder.
# ===== 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 'Initialize-PimHybridWorkerAd'
try {

function Step($m) { Write-Host "[ad] $m" -ForegroundColor Cyan }
function Info($m) { Write-Host "     $m" -ForegroundColor Gray }

# ---------------------------------------------------------------------------------------------------------------------
# REQ 100.42 NO MODULES: every directory read/write below is plain LDAP through .NET (System.DirectoryServices) -- no
# ActiveDirectory module, no RSAT-AD-PowerShell. Each LDAP touch sits behind one small named helper so an offline test
# can stub it. Run on a domain-joined host as an account with the rights listed in the synopsis.
# ---------------------------------------------------------------------------------------------------------------------
Add-Type -AssemblyName System.DirectoryServices
function ConvertTo-PimLdapFilterValue([string]$Value) {
    # RFC 4515 escaping -- names are validated, but a filter is never built from an unescaped value.
    return ($Value -replace '\\', '\5c' -replace '\*', '\2a' -replace '\(', '\28' -replace '\)', '\29' -replace "`0", '\00')
}
function Get-PimAdEntry([string]$Dn) { return (New-Object System.DirectoryServices.DirectoryEntry("LDAP://$Dn")) }
function Test-PimAdDnExists([string]$Dn) { return [System.DirectoryServices.DirectoryEntry]::Exists("LDAP://$Dn") }
function Get-PimAdDomainInfo {
    $root = Get-PimAdEntry 'RootDSE'
    $dn = "$($root.Properties['defaultNamingContext'].Value)"
    $cfgNc = "$($root.Properties['configurationNamingContext'].Value)"
    $d = [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain()
    $s = New-Object System.DirectoryServices.DirectorySearcher((Get-PimAdEntry "CN=Partitions,$cfgNc"), "(&(objectClass=crossRef)(nCName=$(ConvertTo-PimLdapFilterValue $dn)))", [string[]]@('nETBIOSName'))
    $x = $s.FindOne()
    $netb = if ($x) { "$($x.Properties['netbiosname'][0])" } else { (($d.Name -split '\.')[0]).ToUpperInvariant() }
    return [pscustomobject]@{ DNSRoot = $d.Name; NetBIOSName = $netb; PDCEmulator = $d.PdcRoleOwner.Name; DistinguishedName = $dn; ConfigurationNamingContext = $cfgNc }
}
function Find-PimAdObject([string]$LdapFilter, [string]$SearchBase) {
    # One object (or $null) as Name / DistinguishedName / SID -- the fields this script uses.
    $s = New-Object System.DirectoryServices.DirectorySearcher((Get-PimAdEntry $SearchBase), $LdapFilter, [string[]]@('distinguishedName', 'name', 'objectSid'))
    $s.SearchScope = [System.DirectoryServices.SearchScope]::Subtree
    $r = $s.FindOne()
    if (-not $r) { return $null }
    $sid = $null; if ($r.Properties['objectsid'].Count) { $sid = New-Object System.Security.Principal.SecurityIdentifier([byte[]]$r.Properties['objectsid'][0], 0) }
    return [pscustomobject]@{ Name = "$($r.Properties['name'][0])"; DistinguishedName = "$($r.Properties['distinguishedname'][0])"; SID = $sid }
}
function Get-PimAdObjectByDn([string]$Dn) { return (Find-PimAdObject -LdapFilter '(objectClass=*)' -SearchBase $Dn) }
function Test-PimAdKdsRootKey([object]$Domain) {
    # Get-KdsRootKey without the Kds module: the root keys are msKds-ProvRootKey objects in the configuration partition.
    $base = "CN=Master Root Keys,CN=Group Key Distribution Service,CN=Services,$($Domain.ConfigurationNamingContext)"
    if (-not (Test-PimAdDnExists $base)) { return 0 }
    $s = New-Object System.DirectoryServices.DirectorySearcher((Get-PimAdEntry $base), '(objectClass=msKds-ProvRootKey)', [string[]]@('cn'))
    $s.SearchScope = [System.DirectoryServices.SearchScope]::OneLevel
    return @($s.FindAll()).Count
}
function Get-PimAdKdsRootKeyNewestUtc([object]$Domain) {
    # The newest root key's creation time (msKds-CreateTime, a FILETIME), or $null. Domain controllers hand out gMSA
    # passwords only from a key that is ~10 hours old (replication), so a young key explains a failing gMSA test.
    $base = "CN=Master Root Keys,CN=Group Key Distribution Service,CN=Services,$($Domain.ConfigurationNamingContext)"
    if (-not (Test-PimAdDnExists $base)) { return $null }
    $s = New-Object System.DirectoryServices.DirectorySearcher((Get-PimAdEntry $base), '(objectClass=msKds-ProvRootKey)', [string[]]@('msKds-CreateTime'))
    $s.SearchScope = [System.DirectoryServices.SearchScope]::OneLevel
    $newest = $null
    foreach ($r in @($s.FindAll())) {
        if (-not $r.Properties['mskds-createtime'].Count) { continue }
        $t = [datetime]::FromFileTimeUtc([int64]$r.Properties['mskds-createtime'][0])
        if (-not $newest -or $t -gt $newest) { $newest = $t }
    }
    return $newest
}
$script:KdsCreatedUtc = $null
function Test-PimAdPamFeatureEnabled([object]$Domain) {
    $dn = "CN=Privileged Access Management Feature,CN=Optional Features,CN=Directory Service,CN=Windows NT,CN=Services,$($Domain.ConfigurationNamingContext)"
    if (-not (Test-PimAdDnExists $dn)) { return $false }
    return ((Get-PimAdEntry $dn).Properties['msDS-EnabledFeatureBL'].Count -gt 0)
}
function New-PimAdGroupObject([string]$Name, [string]$Ou, [string]$Description) {
    $e = (Get-PimAdEntry $Ou).Children.Add("CN=$Name", 'group')
    [void]$e.Properties['sAMAccountName'].Add($Name)
    [void]$e.Properties['groupType'].Add([int]-2147483646)   # 0x80000002 = global security group
    if ("$Description".Trim()) { [void]$e.Properties['description'].Add($Description) }
    $e.CommitChanges()
    return (Get-PimAdObjectByDn "CN=$Name,$Ou")
}
function Test-PimAdGroupHasMember([object]$Group, [object]$Member) {
    foreach ($m in @((Get-PimAdEntry $Group.DistinguishedName).Properties['member'])) { if ("$m" -ieq "$($Member.DistinguishedName)") { return $true } }
    return $false
}
function Add-PimAdGroupMember([object]$Group, [object]$Member) {
    $e = Get-PimAdEntry $Group.DistinguishedName
    [void]$e.Properties['member'].Add("$($Member.DistinguishedName)")
    $e.CommitChanges()
}
function New-PimAdGmsaObject([string]$Name, [string]$Ou, [string]$DnsHostName, [object]$AllowedPrincipal, [string]$Description) {
    # New-ADServiceAccount without the module: an msDS-GroupManagedServiceAccount object. AES256 only (msDS-SupportedEncryptionTypes
    # 0x10), 30-day password interval, WORKSTATION_TRUST_ACCOUNT (4096), and msDS-GroupMSAMembership = the security descriptor
    # naming who may retrieve the password (owner BUILTIN\Administrators, one allow ACE for the PrincipalsAllowedAccess group).
    if (-not $AllowedPrincipal -or -not $AllowedPrincipal.SID) { throw "gMSA ${Name}: the PrincipalsAllowedAccess group must exist before the gMSA" }
    $sd = New-Object System.Security.AccessControl.RawSecurityDescriptor("O:S-1-5-32-544D:(A;;0x3;;;$($AllowedPrincipal.SID.Value))")
    $bin = New-Object byte[] $sd.BinaryLength; $sd.GetBinaryForm($bin, 0)
    $e = (Get-PimAdEntry $Ou).Children.Add("CN=$Name", 'msDS-GroupManagedServiceAccount')
    [void]$e.Properties['sAMAccountName'].Add("$Name`$")
    [void]$e.Properties['dNSHostName'].Add($DnsHostName)
    [void]$e.Properties['userAccountControl'].Add([int]4096)
    [void]$e.Properties['msDS-ManagedPasswordInterval'].Add([int]30)
    [void]$e.Properties['msDS-SupportedEncryptionTypes'].Add([int]16)
    [void]$e.Properties['msDS-GroupMSAMembership'].Add($bin)
    if ("$Description".Trim()) { [void]$e.Properties['description'].Add($Description) }
    $e.CommitChanges()
    return (Get-PimAdObjectByDn "CN=$Name,$Ou")
}
function Find-PimAdGpo([string]$DisplayName, [object]$Domain) {
    # Get-GPO -Name without the module: the groupPolicyContainer whose displayName matches; Id = its cn without braces.
    $s = New-Object System.DirectoryServices.DirectorySearcher((Get-PimAdEntry "CN=Policies,CN=System,$($Domain.DistinguishedName)"), "(&(objectClass=groupPolicyContainer)(displayName=$(ConvertTo-PimLdapFilterValue $DisplayName)))", [string[]]@('cn'))
    $s.SearchScope = [System.DirectoryServices.SearchScope]::OneLevel
    $r = $s.FindOne()
    if (-not $r) { return $null }
    return [pscustomobject]@{ Id = [guid]("$($r.Properties['cn'][0])".Trim('{', '}')); DisplayName = $DisplayName }
}
function New-PimAdGpo([string]$DisplayName, [string]$Comment) {
    # owner exception 2026-10-09, framework §12.17 -- GroupPolicy module (GPO create/link) on the hybrid worker only
    # (GroupPolicy has no .NET API). CREATING a GPO means a groupPolicyContainer plus its SYSVOL folder with matching ACLs (what GPMC does); hand-writing both is fragile, so this ONE step still uses
    # the GroupPolicy module, and only when the GPO does not exist yet. Reading, the CSE/version bump and linking are LDAP.
    Import-Module GroupPolicy
    $g = New-GPO -Name $DisplayName -Comment $Comment
    return [pscustomobject]@{ Id = [guid]$g.Id; DisplayName = $DisplayName }
}
function Test-PimAdGpoLinked([string]$Ou, [guid]$GpoId) {
    $cur = "$((Get-PimAdEntry $Ou).Properties['gPLink'].Value)"
    return $cur.ToLowerInvariant().Contains(("cn={{{0}}},cn=policies,cn=system," -f $GpoId.ToString()).ToLowerInvariant())
}
function Add-PimAdGpoLink([string]$Ou, [guid]$GpoId, [object]$Domain) {
    # New-GPLink -LinkEnabled Yes without the module: gPLink lists links lowest-precedence FIRST, so a new link (order = last,
    # like New-GPLink) is PREPENDED. Flag 0 = enabled, not enforced.
    $e = Get-PimAdEntry $Ou
    $cur = "$($e.Properties['gPLink'].Value)"
    $e.Properties['gPLink'].Value = ("[LDAP://cn={{{0}}},cn=policies,cn=system,{1};0]" -f $GpoId.ToString(), $Domain.DistinguishedName) + $cur
    $e.CommitChanges()
}
function Get-PimAdGpoVersionState([string]$GpoDn) {
    $e = Get-PimAdEntry $GpoDn
    return [pscustomobject]@{ gPCMachineExtensionNames = "$($e.Properties['gPCMachineExtensionNames'].Value)"; versionNumber = [int]"0$($e.Properties['versionNumber'].Value)" }
}
function Set-PimAdGpoVersionState([string]$GpoDn, [string]$Extensions, [int]$Version) {
    $e = Get-PimAdEntry $GpoDn
    $e.Properties['gPCMachineExtensionNames'].Value = $Extensions
    $e.Properties['versionNumber'].Value = $Version
    $e.CommitChanges()
}

$dom = Get-PimAdDomainInfo
$net = $dom.NetBIOSName
Step "domain $($dom.DNSRoot) ($net), PDC $($dom.PDCEmulator)"
if ("$ServerGmsaName".Trim() -and -not @($ServerOu | Where-Object { "$_".Trim() }).Count) { throw '-ServerGmsaName needs -ServerOu: the OU(s) whose servers get its PermissionGroup as local administrator (the GPO)' }
if ("$ServerGmsaName".Trim() -ieq $GmsaName) { throw '-ServerGmsaName must differ from -GmsaName: server onboarding is a separate tier' }
foreach ($ou in @($ComputerOu, $GmsaOu, $GroupsOu) + @($AdminAccountsOu) + @($ServerOu)) {
    if (-not "$ou".Trim()) { continue }
    if (-not (Test-PimAdDnExists $ou)) { throw "OU not found: '$ou'" }
}

# 1. KDS root key
$kdsCount = Test-PimAdKdsRootKey -Domain $dom
if (-not $kdsCount) {
    if (-not $CreateKdsRootKey) { throw 'No KDS root key: a gMSA cannot exist without one. Re-run with -CreateKdsRootKey (forest-wide; effective after replication, ~10 h unless backdated), or create it yourself.' }
    # owner exception 2026-10-09, framework §12.17 -- on-prem AD / GroupPolicy on the hybrid worker (KDS root key: opt-in, Tier-0 box)
    # The KDS root key is generated by the Key Distribution Service itself (no LDAP/.NET way to mint one), so Add-KdsRootKey
    # (the in-box Kds module) stays ONLY behind the opt-in -CreateKdsRootKey, a one-time forest operation.
    if ($PSCmdlet.ShouldProcess('forest', 'Add-KdsRootKey (effective in 10 hours)')) {
        Add-KdsRootKey -EffectiveImmediately | Out-Null
        $script:KdsCreatedUtc = (Get-Date).ToUniversalTime()
        Write-Host ("     NOTE -- a NEW KDS root key was created {0:yyyy-MM-dd HH:mm} UTC. Domain controllers use it only after ~10 hours (replication):" -f $script:KdsCreatedUtc) -ForegroundColor Yellow
        Write-Host ("     the gMSAs below are created now, but the worker can install / use them from about {0:yyyy-MM-dd HH:mm} UTC. Wait -- do NOT backdate the key" -f $script:KdsCreatedUtc.AddHours(10)) -ForegroundColor Yellow
        Write-Host '     (Add-KdsRootKey -EffectiveTime (Get-Date).AddHours(-10) is a single-DC LAB shortcut only; in a real forest it breaks gMSA on DCs that have not replicated).' -ForegroundColor Yellow
    }
} else {
    $newest = Get-PimAdKdsRootKeyNewestUtc -Domain $dom
    Info "KDS root key present ($kdsCount)$(if ($newest) { ', newest created ' + $newest.ToString('yyyy-MM-dd HH:mm') + ' UTC' })"
    if ($newest -and $newest -gt (Get-Date).ToUniversalTime().AddHours(-10)) {
        $script:KdsCreatedUtc = $newest
        Write-Host ("     NOTE -- the newest KDS root key is younger than 10 hours: gMSAs work from about {0:yyyy-MM-dd HH:mm} UTC." -f $newest.AddHours(10)) -ForegroundColor Yellow
    }
}

# PAM feature: detect, never enable
$pam = Test-PimAdPamFeatureEnabled -Domain $dom
Info ("AD Privileged Access Management feature: {0}" -f $(if ($pam) { 'ENABLED -- JIT membership will carry a TTL' } else { 'not enabled -- JIT membership is plain; the sync removes it (this script never enables PAM: it is irreversible)' }))

# 2. worker computer + offline domain-join blob
$comp = Find-PimAdObject -LdapFilter "(&(objectCategory=computer)(name=$(ConvertTo-PimLdapFilterValue $WorkerComputerName)))" -SearchBase $dom.DistinguishedName
if ($ProvisionOdj) {
    if ($comp -and -not $ReuseComputer) { throw "Computer '$WorkerComputerName' already exists ($($comp.DistinguishedName)). Pass -ReuseComputer to re-provision it (its password is reset)." }
    if ($PSCmdlet.ShouldProcess($WorkerComputerName, "djoin /provision in '$ComputerOu'")) {
        $tmp = Join-Path $env:TEMP ("odj-{0}.txt" -f ([guid]::NewGuid().ToString('N')))
        try {
            $dj = @('/provision', '/domain', $dom.DNSRoot, '/machine', $WorkerComputerName, '/machineou', $ComputerOu, '/savefile', $tmp)
            if ($comp) { $dj += '/reuse' }
            $out = & djoin.exe @dj 2>&1
            if ($LASTEXITCODE -ne 0) { throw "djoin /provision failed ($LASTEXITCODE): $($out -join ' ')" }
            # gzip + base64 ('gz:' prefix): the raw file is UTF-16 base64 text, ~4x larger, and Azure run-command returns only
            # the last 4 KB of output -- an uncompressed blob arrives truncated and the join fails far from the cause.
            $ms = New-Object IO.MemoryStream
            $gz = New-Object IO.Compression.GZipStream($ms, [IO.Compression.CompressionMode]::Compress)
            $raw = [IO.File]::ReadAllBytes($tmp); $gz.Write($raw, 0, $raw.Length); $gz.Close()
            $blob = 'gz:' + [Convert]::ToBase64String($ms.ToArray())
            Write-Output 'ODJ-BLOB-BEGIN'; Write-Output $blob; Write-Output 'ODJ-BLOB-END'
        } finally { if (Test-Path $tmp) { Remove-Item -LiteralPath $tmp -Force } }
        $comp = Find-PimAdObject -LdapFilter "(&(objectCategory=computer)(name=$(ConvertTo-PimLdapFilterValue $WorkerComputerName)))" -SearchBase $dom.DistinguishedName
    }
} elseif (-not $comp) { Info "computer '$WorkerComputerName' does not exist yet (join it first, or use -ProvisionOdj) -- the PrincipalsAllowedAccess groups are created empty" }

# 3. identities: gMSA + <name>-PermissionGroup + <name>-PrincipalsAllowedAccess
function Get-OrNewGroup([string]$Name, [string]$Description) {
    $g = Find-PimAdObject -LdapFilter "(&(objectCategory=group)(name=$(ConvertTo-PimLdapFilterValue $Name)))" -SearchBase $dom.DistinguishedName
    if (-not $g -and $PSCmdlet.ShouldProcess($Name, "create global security group in '$GmsaOu'")) {
        $g = New-PimAdGroupObject -Name $Name -Ou $GmsaOu -Description $Description
        Info "group $Name created"
    } elseif ($g) { Info "group $Name exists" }
    return $g
}
function Add-Member([object]$Group, [object]$Member, [string]$What) {
    if (-not $Group -or -not $Member) { return }
    if (Test-PimAdGroupHasMember -Group $Group -Member $Member) { Info "$What already in $($Group.Name)"; return }
    if ($PSCmdlet.ShouldProcess($Group.Name, "add $What")) { Add-PimAdGroupMember -Group $Group -Member $Member; Info "$What added to $($Group.Name)" }
}
function Initialize-Identity([string]$Name, [string]$Purpose) {
    $lt = if ($Name -match '-(L\d)-(T\d)$') { "$($Matches[1]), $($Matches[2])" } else { '' }
    $paa = Get-OrNewGroup -Name "$Name-PrincipalsAllowedAccess" -Description "Principals Allowed to retrieve password for $Name"
    Add-Member -Group $paa -Member $comp -What "$WorkerComputerName`$ (the worker needs a reboot or a Kerberos purge to see it)"
    $gm = Find-PimAdObject -LdapFilter "(&(objectClass=msDS-GroupManagedServiceAccount)(name=$(ConvertTo-PimLdapFilterValue $Name)))" -SearchBase $dom.DistinguishedName
    if (-not $gm -and $PSCmdlet.ShouldProcess("$Name`$", "create gMSA in '$GmsaOu'")) {
        # the gMSA trusts "$Name-PrincipalsAllowedAccess" (msDS-GroupMSAMembership): only its members retrieve the password
        $gm = New-PimAdGmsaObject -Name $Name -Ou $GmsaOu -DnsHostName "$Name.$($dom.DNSRoot)" -AllowedPrincipal $paa `
            -Description ("{0}{1} | Used by {2}" -f $Purpose, $(if ($lt) { " ($lt)" } else { '' }), $UsedBy)
        Info "gMSA $Name`$ created"
    } elseif ($gm) { Info "gMSA $Name`$ exists" }
    $pg = Get-OrNewGroup -Name "$Name-PermissionGroup" -Description "Permission-group for $Name"
    if ($gm) { Add-Member -Group $pg -Member $gm -What "$Name`$" }
    return $pg
}
Step "identity $GmsaName (AD groups, JIT membership, admin accounts)"
$perm = Initialize-Identity -Name $GmsaName -Purpose 'PIM for AD: groups, just-in-time membership, admin accounts'
$srvPerm = $null
if ("$ServerGmsaName".Trim()) {
    Step "identity $ServerGmsaName (server onboarding)"
    $srvPerm = Initialize-Identity -Name $ServerGmsaName -Purpose 'PIM for AD: server local administrators / resource onboarding'
}

# 4. rights -- on the PermissionGroup (dsacls /G adds, never duplicates)
$who = "$net\$GmsaName-PermissionGroup"
function Grant-Ace([string]$Dn, [string[]]$Specs, [string]$Why) {
    foreach ($s in $Specs) {
        if ($PSCmdlet.ShouldProcess($Dn, "dsacls $s -> $who ($Why)")) {
            $a = $s -split ' ', 2
            $out = & dsacls.exe $Dn $a[0] /G "$($who):$($a[1])" 2>&1
            if ($LASTEXITCODE -ne 0) { throw "dsacls failed on '$Dn' ($s): $($out -join ' ')" }
        }
    }
    Info "$Why -> $Dn"
}
# READ on the OU itself first (2026-10-04, internal: the Delegation Groups OU had inheritance OFF, so the worker could
# not even see it and every create failed with "Cannot find an object with identity").
Grant-Ace -Dn $GroupsOu -Why 'PIM-for-AD groups: read the OU + create + member/displayName/description' -Specs @('/I:T GR', '/I:T CC;group', '/I:S RPWP;member;group', '/I:S RPWP;displayName;group', '/I:S RPWP;description;group')
if ($AllowGroupCleanup) {
    # PIM 100.123: "Delete Group objects" on the groups OU (this object and all descendants). Nothing is deleted by this
    # grant: the worker deletes only the exact groups a SuperAdmin approved on the clean-up review page.
    Grant-Ace -Dn $GroupsOu -Why 'PIM-for-AD groups: delete group objects (the reviewed clean-up of old PIM groups)' -Specs @('/I:T DC;group')
}
foreach ($ou in @($AdminAccountsOu | Where-Object { "$_".Trim() })) {
    Grant-Ace -Dn $ou -Why 'admin accounts: create users + full control of the users below' -Specs @('/I:T CC;user', '/I:S GA;;user')
}
if ($GrantProtectedGroupMembership) {
    $sdh = "CN=AdminSDHolder,CN=System,$($dom.DistinguishedName)"
    Write-Host "     WARNING -- AdminSDHolder: '$who' may change the members of every protected group -- it is TIER 0 from here on." -ForegroundColor Yellow
    Grant-Ace -Dn $sdh -Why 'protected groups (adminCount=1): write member' -Specs @('/I:T RPWP;member')
    if ($TriggerSdProp -and $PSCmdlet.ShouldProcess($dom.PDCEmulator, 'runProtectAdminGroupsTask (apply AdminSDHolder now, not within the hour)')) {
        $root = [ADSI]"LDAP://$($dom.PDCEmulator)/RootDSE"; $root.Put('runProtectAdminGroupsTask', 1); $root.SetInfo(); Info 'SDProp triggered on the PDC'
    }
}

# 5. servers GPO: Restricted Groups "member of" BUILTIN\Administrators for the server identity's PermissionGroup
if ($srvPerm -and $comp) {
    # The worker is Tier 0: the Tier-1 server identity must not become local administrator ON it (an on-premises Arc
    # worker is an existing server and may well sit in the servers OU).
    foreach ($ou in @($ServerOu | Where-Object { "$_".Trim() })) {
        if ("$($comp.DistinguishedName)" -like "*,$ou") { Write-Host "     WARNING -- the worker $WorkerComputerName is below -ServerOu '$ou': the servers GPO would make $ServerGmsaName (Tier 1) local administrator on this Tier-0 machine. Move the worker out of that OU (or block inheritance for it)." -ForegroundColor Yellow }
    }
}
if ($srvPerm) {
    $gpoName = if ("$ServerAdminGpoName".Trim()) { "$ServerAdminGpoName".Trim() } else { "PIM for AD: $ServerGmsaName-PermissionGroup is local administrator (servers)" }
    Step "servers GPO '$gpoName'"
    $gpo = Find-PimAdGpo -DisplayName $gpoName -Domain $dom
    if (-not $gpo -and $PSCmdlet.ShouldProcess($gpoName, 'New-GPO')) { $gpo = New-PimAdGpo -DisplayName $gpoName -Comment "Adds $net\$ServerGmsaName-PermissionGroup to BUILTIN\Administrators (nothing removed). Owned by the $UsedBy setup." }
    if ($gpo) {
        $sidTxt = $srvPerm.SID.Value
        $line = "*$sidTxt`__Memberof = *S-1-5-32-544"
        $dir = "\\$($dom.DNSRoot)\SYSVOL\$($dom.DNSRoot)\Policies\{$($gpo.Id)}\Machine\Microsoft\Windows NT\SecEdit"
        $inf = Join-Path $dir 'GptTmpl.inf'
        $cur = if (Test-Path $inf) { Get-Content -LiteralPath $inf -Encoding Unicode } else { @() }
        $wrote = $false
        if (@($cur | Where-Object { $_ -eq $line }).Count) { Info 'Restricted Groups entry present' }
        elseif ($PSCmdlet.ShouldProcess($inf, "write '$line'")) {
            New-Item -ItemType Directory -Force $dir | Out-Null
            $body = @('[Unicode]', 'Unicode=yes', '[Version]', 'signature="$CHICAGO$"', 'Revision=1', '[Group Membership]', $line)
            Set-Content -LiteralPath $inf -Value $body -Encoding Unicode
            $wrote = $true
            Info "Restricted Groups: $net\$ServerGmsaName-PermissionGroup -> BUILTIN\Administrators"
        }
        # the security CSE + a version bump, or clients never process the settings -- checked on EVERY run on its own (a run
        # that failed after writing the file must not leave a GPO clients ignore). .Contains, never -like: the value has [ ].
        $gpoDn = "CN={$($gpo.Id)},CN=Policies,CN=System,$($dom.DistinguishedName)"
        $o = Get-PimAdGpoVersionState -GpoDn $gpoDn
        $cse = '[{827D319E-6EAC-11D2-A4EA-00C04F79F83A}{803E14A0-B4FB-11D0-A0D0-00A0C9055D1C}]'
        $ext = "$($o.gPCMachineExtensionNames)"
        if (($wrote -or -not $ext.Contains($cse)) -and $PSCmdlet.ShouldProcess($gpoDn, 'security CSE + version bump')) {
            if (-not $ext.Contains($cse)) { $ext = "$ext$cse" }
            $ver = [int]$o.versionNumber + 1
            Set-PimAdGpoVersionState -GpoDn $gpoDn -Extensions $ext -Version $ver
            $gptIni = "\\$($dom.DNSRoot)\SYSVOL\$($dom.DNSRoot)\Policies\{$($gpo.Id)}\GPT.INI"
            Set-Content -LiteralPath $gptIni -Value @('[General]', "Version=$ver") -Encoding ASCII
            Info "GPO version $ver (security settings extension registered)"
        } else { Info 'security settings extension registered' }
        foreach ($ou in @($ServerOu | Where-Object { "$_".Trim() })) {
            $linked = Test-PimAdGpoLinked -Ou $ou -GpoId $gpo.Id
            if ($linked) { Info "linked to $ou" }
            elseif ($PSCmdlet.ShouldProcess($ou, "New-GPLink '$gpoName'")) { Add-PimAdGpoLink -Ou $ou -GpoId $gpo.Id -Domain $dom; Info "linked to $ou -- effective at each server's next policy refresh (gpupdate /target:computer)" }
        }
    }
}

Write-Host ''
Write-Host ("[ad] done. On the worker: Install-PimHybridWorker.ps1 -GmsaName '{0}\{1}'{2} (it installs and TESTS each gMSA)." -f $net, $GmsaName, $(if ("$ServerGmsaName".Trim()) { " -ServerGmsaName '$net\$ServerGmsaName'" } else { '' })) -ForegroundColor Green
Write-Host "     Set in Manager > Settings > Hybrid Active Directory: OU for new AD groups = '$GroupsOu'" -ForegroundColor Green
# Deploy-PimHybridWorker.ps1 stopped for this step: tell it how to go on (and whether it must wait for the KDS key).
$resume = '-Resume' + $(if ($script:KdsCreatedUtc) { " -KdsRootKeyCreatedUtc '$($script:KdsCreatedUtc.ToString('yyyy-MM-ddTHH:mm:ssZ'))'" } else { '' }) +
    $(if ($ProvisionOdj) { " -OdjBlobFile <a file holding the line between ODJ-BLOB-BEGIN / ODJ-BLOB-END>" } else { '' })
Write-Host "     Using Deploy-PimHybridWorker.ps1? Continue it with: Deploy-PimHybridWorker.ps1 $resume -Apply" -ForegroundColor Green

} finally { Stop-PimScriptRun -Script 'Initialize-PimHybridWorkerAd' }