@trillboards/edge-sdk 0.2.24 → 0.2.26

package/deploy/windows/build-windows.ps1

@@ -202,6 +202,7 @@ Copy-Item -Force "$Here\trillboards-hidden-run.vbs" "$Payload\bin\trillboards-hi
 Copy-Item -Force "$Here\ensure-sensing.ps1"   "$Payload\bin\ensure-sensing.ps1"
 Copy-Item -Force "$Here\run-connector.ps1"      "$Payload\bin\run-connector.ps1"
 Copy-Item -Force "$Here\register-task.ps1"    "$Payload\bin\register-task.ps1"
+Copy-Item -Force "$Here\enroll-connector.ps1" "$Payload\bin\enroll-connector.ps1"
 Copy-Item -Force "$Here\stop-existing.ps1"    "$Payload\bin\stop-existing.ps1"
 Copy-Item -Force "$Here\install-update.ps1"    "$Payload\bin\install-update.ps1"
 # The in-field updater. Ships in bin\ so an INSTALLED connector can drive its own

package/deploy/windows/ci/verify-update-applier.ps1

@@ -67,8 +67,81 @@ $Www = Join-Path $Root 'www'
 $Certs = New-Object System.Collections.Generic.List[string]
 $LocalUser = 'tbupd'
 $Failures = 0
+$StartedAt = Get-Date
 
-function Say([string]$m) { Write-Host "[update-applier] $m" }
+<#
+  A SELF-IMPOSED DEADLINE, because the first run of this harness did not fail -
+  it ate the whole job. It printed ONE line, ran for 11 minutes, and the JOB hit
+  its 15-minute cap, so every other proof in that step lost its budget too and
+  the log said only "The operation was canceled" - naming no cause and proving
+  nothing. Not one arm had run.
+
+  A harness that cannot finish must say so ITSELF, at the point it gives up, and
+  loudly enough to be actionable. Every phase below also prints its elapsed
+  time, because the reason that first failure was undiagnosable was that there
+  was no output between "origin listening" and the first arm.
+#>
+$DeadlineMinutes = 8
+
+function Elapsed { ((Get-Date) - $script:StartedAt).TotalSeconds }
+function Say([string]$m) { Write-Host ("[update-applier {0,6:N1}s] {1}" -f (Elapsed), $m) }
+
+$script:CurrentPhase = 'startup'
+
+function Fail-Deadline([string]$Phase, [string]$When) {
+  Write-Host "FAIL - the harness exceeded its $($script:DeadlineMinutes)-minute deadline $When`: $Phase"
+  Write-Host '       HARNESS BUDGET failure, not a product failure. The arms above ran;'
+  Write-Host '       the ones below never started. Read the per-phase timings to find'
+  Write-Host '       what got slow before assuming a defect in apply-update.ps1.'
+  Cleanup
+  exit 1
+}
+
+function Assert-WithinDeadline([string]$Phase) {
+  $script:CurrentPhase = $Phase
+  if (((Get-Date) - $script:StartedAt).TotalMinutes -lt $script:DeadlineMinutes) { return }
+  Fail-Deadline $Phase 'before starting'
+}
+
+function Remaining-DeadlineSeconds {
+  [Math]::Max(0, ($script:DeadlineMinutes * 60) - (Elapsed))
+}
+
+<#
+  Wait for a process, but never past the harness deadline.
+
+  Assert-WithinDeadline can only sample time BETWEEN phases, so on its own it
+  cannot stop a phase that is ALREADY blocked - and that is precisely the
+  failure this harness exists to prevent. The first run spent eleven minutes
+  inside a single call; the job's 15-minute cap ended it, the harness did not,
+  and the log named no cause. A deadline that can only fire between the things
+  it is bounding is not a deadline.
+
+  So every blocking wait goes through here, bounded by the budget REMAINING at
+  the moment the wait starts. The deadline therefore stays a whole-harness
+  deadline rather than becoming a per-call timeout: eight slow phases cannot
+  each consume eight minutes.
+
+  On expiry we kill the process before reporting, so the cleanup that follows
+  is not itself blocked by the thing that hung.
+#>
+function Wait-Bounded {
+  param([System.Diagnostics.Process]$Process, [string]$Phase = $script:CurrentPhase)
+  $budget = Remaining-DeadlineSeconds
+  if ($budget -le 0) {
+    try { Stop-Process -Id $Process.Id -Force -ErrorAction SilentlyContinue } catch {}
+    Fail-Deadline $Phase 'before starting'
+  }
+  $exited = $false
+  try { $exited = $Process.WaitForExit([int]([Math]::Min(2147483, $budget) * 1000)) } catch { $exited = $true }
+  if (-not $exited) {
+    try { Stop-Process -Id $Process.Id -Force -ErrorAction SilentlyContinue } catch {}
+    try { $Process.WaitForExit(5000) | Out-Null } catch {}
+    Fail-Deadline $Phase 'while running'
+  }
+  try { $Process.Refresh() } catch {}
+  return $Process
+}
 function Pass([string]$m) { Write-Host "PASS - $m" }
 function Bad([string]$m) { Write-Host "FAIL - $m"; $script:Failures++ }
 function Die([string]$m) { Write-Host "FAIL - $m"; Cleanup; exit 1 }
@@ -158,27 +231,70 @@ function Sign-File([string]$Path, $Cert) {
 # ---------------------------------------------------------------------------
 # Fixtures
 # ---------------------------------------------------------------------------
+<#
+  BUILT ONCE, REUSED. The first version of this harness rebuilt the whole tree
+  per arm: 4 trees x (copy the runner's ~110 MB node.exe + Authenticode-sign 12
+  scripts + zip the lot). On windows-latest that produced ONE line of output and
+  then nothing for 11 minutes, until the job hit its 15-minute cap and was
+  cancelled - so not one arm ever ran, and the step looked hung rather than slow
+  because there was no progress output between phases at all.
+
+  Two fixes, and the second is the one that matters for the next person:
+
+  1. Sign the shipped script set ONCE into a cache and COPY the signed bytes
+     into each tree. Authenticode signing is the expensive part, not the file
+     copy, and the signatures are identical across trees by construction.
+  2. bin\node.exe is a small system PE re-signed with the harness certificate,
+     NOT the real 110 MB node. The applier only needs it to be PRESENT and
+     VALID; the two arms that actually EXECUTE node ask for -RealNode. Re-signing
+     also removes the Microsoft CRL distribution point, so the applier's
+     Get-AuthenticodeSignature calls resolve against a self-signed chain with
+     nothing to look up instead of reaching for the network 13 times per stage.
+#>
+$SignedCache = $null
+
+function Initialize-SignedCache($SignCert) {
+  if ($script:SignedCache) { return }
+  $script:SignedCache = Join-Path $Root 'signed-cache'
+  New-Item -ItemType Directory -Force -Path $script:SignedCache | Out-Null
+  $t0 = Get-Date
+  foreach ($f in @(& (Join-Path $Here 'list-shipped-scripts.ps1') -Kind signable -AbsolutePath)) {
+    $dest = Join-Path $script:SignedCache (Split-Path -Leaf $f)
+    Copy-Item -LiteralPath $f -Destination $dest -Force
+    Sign-File $dest $SignCert
+  }
+  # A small, already-PE stub that becomes bin\node.exe. where.exe is ~40 KB and
+  # is a real signed PE, so re-signing it with the harness cert succeeds and the
+  # result carries OUR chain rather than Microsoft's.
+  $stub = Join-Path $script:SignedCache 'node.exe'
+  Copy-Item -LiteralPath (Join-Path $env:WINDIR 'System32\where.exe') -Destination $stub -Force
+  Sign-File $stub $SignCert
+  Say ("signed-script cache built in {0:N1}s" -f ((Get-Date) - $t0).TotalSeconds)
+}
+
 <#
   A tree shaped exactly like the shipped connector: bin\ with the real scripts
   (so the applier's "at least 10 signed executables" floor is met by the real
   file set, not a stub), a node.exe, and a cli.js that answers `version` the way
   install-update.ps1 requires.
 #>
-function New-PayloadTree([string]$Dest, $SignCert, [switch]$LogonOnlyRegisterTask, [switch]$WithUnsignedScript) {
+function New-PayloadTree([string]$Dest, $SignCert, [switch]$LogonOnlyRegisterTask, [switch]$WithUnsignedScript, [switch]$RealNode) {
+  Initialize-SignedCache $SignCert
+  $t0 = Get-Date
   if (Test-Path -LiteralPath $Dest) { Remove-Item -LiteralPath $Dest -Recurse -Force }
   $bin = Join-Path $Dest 'bin'
   $dist = Join-Path $Dest 'lib\edge-sdk\dist'
   New-Item -ItemType Directory -Force -Path $bin, $dist | Out-Null
 
-  foreach ($f in @(& (Join-Path $Here 'list-shipped-scripts.ps1') -Kind signable -AbsolutePath)) {
-    Copy-Item -LiteralPath $f -Destination (Join-Path $bin (Split-Path -Leaf $f)) -Force
-  }
+  Copy-Item -Path (Join-Path $script:SignedCache '*') -Destination $bin -Force
+
   if ($LogonOnlyRegisterTask) {
     # A register-task.ps1 that deliberately produces the PRE-headless shape.
     # This is how arm J reproduces, on an elevated runner, the downgrade a
     # non-elevated field caller would suffer: the cause differs, the observable
     # (the task comes back logon-only) is identical, and that observable is what
-    # the guard keys on.
+    # the guard keys on. Signed, or the payload would be refused by the
+    # signature check before it could ever reach install-update.ps1.
     $downgrade = @'
 [CmdletBinding()]
 param([Parameter(Mandatory = $true)][string]$InstallDir, [string]$Mode = "auto-sense")
@@ -190,29 +306,28 @@ $principal = New-ScheduledTaskPrincipal -UserId $UserId -LogonType Interactive -
 Unregister-ScheduledTask -TaskName "TrillboardsEdge" -Confirm:$false -ErrorAction SilentlyContinue
 Register-ScheduledTask -TaskName "TrillboardsEdge" -Action $action -Trigger $trigger -Principal $principal | Out-Null
 '@
-    [System.IO.File]::WriteAllText((Join-Path $bin 'register-task.ps1'), $downgrade, (New-Object System.Text.UTF8Encoding($false)))
+    $rt = Join-Path $bin 'register-task.ps1'
+    [System.IO.File]::WriteAllText($rt, $downgrade, (New-Object System.Text.UTF8Encoding($false)))
+    Sign-File $rt $SignCert
   }
   if ($WithUnsignedScript) {
     [System.IO.File]::WriteAllText((Join-Path $bin 'rogue.ps1'), "exit 0`r`n", (New-Object System.Text.UTF8Encoding($false)))
   }
+  if ($RealNode) {
+    # Only the arms that actually RUN the connector need a real interpreter.
+    Copy-Item -LiteralPath (Get-Command node).Source -Destination (Join-Path $bin 'node.exe') -Force
+    $nodeSig = Get-AuthenticodeSignature -LiteralPath (Join-Path $bin 'node.exe')
+    if ($nodeSig.Status -ne 'Valid') { Sign-File (Join-Path $bin 'node.exe') $SignCert }
+  }
 
-  Copy-Item -LiteralPath (Get-Command node).Source -Destination (Join-Path $bin 'node.exe') -Force
   [System.IO.File]::WriteAllText(
     (Join-Path $dist 'cli.js'),
     "if (process.argv[2] === 'version') { console.log('@trillboards/edge-sdk v9.9.9'); process.exit(0); }`r`nsetInterval(function(){}, 1000);`r`n",
     (New-Object System.Text.UTF8Encoding($false)))
-
-  foreach ($f in @(Get-ChildItem -LiteralPath $bin -File | Where-Object { $_.Name -ne 'rogue.ps1' })) {
-    if ($f.Extension -in @('.ps1', '.vbs')) { Sign-File $f.FullName $SignCert }
-  }
-  # The runner's node.exe is the official OpenJS build and already Valid; sign a
-  # copy only if it is not, so the floor check measures signatures rather than
-  # the runner image.
-  $nodeSig = Get-AuthenticodeSignature -LiteralPath (Join-Path $bin 'node.exe')
-  if ($nodeSig.Status -ne 'Valid') { Sign-File (Join-Path $bin 'node.exe') $SignCert }
+  Say ("payload tree $(Split-Path -Leaf $Dest) built in {0:N1}s (realNode=$RealNode)" -f ((Get-Date) - $t0).TotalSeconds)
 }
 
-function New-InstallTree([string]$Dest) {
+function New-InstallTree([string]$Dest, [switch]$RealNode) {
   if (Test-Path -LiteralPath $Dest) { Remove-Item -LiteralPath $Dest -Recurse -Force }
   $bin = Join-Path $Dest 'bin'
   $dist = Join-Path $Dest 'lib\edge-sdk\dist'
@@ -220,7 +335,14 @@ function New-InstallTree([string]$Dest) {
   foreach ($f in @('stop-existing.ps1', 'register-task.ps1', 'install-update.ps1', 'apply-update.ps1', 'run-connector.ps1', 'trillboards-edge-task.vbs')) {
     Copy-Item -LiteralPath (Join-Path $Deploy $f) -Destination (Join-Path $bin $f) -Force
   }
-  Copy-Item -LiteralPath (Get-Command node).Source -Destination (Join-Path $bin 'node.exe') -Force
+  # Same reasoning as the payload tree: only the arms that RUN the connector
+  # need a real interpreter, and copying ~110 MB per arm is what blew the job
+  # budget the first time this harness ran.
+  if ($RealNode) {
+    Copy-Item -LiteralPath (Get-Command node).Source -Destination (Join-Path $bin 'node.exe') -Force
+  } elseif ($script:SignedCache -and (Test-Path -LiteralPath (Join-Path $script:SignedCache 'node.exe'))) {
+    Copy-Item -LiteralPath (Join-Path $script:SignedCache 'node.exe') -Destination (Join-Path $bin 'node.exe') -Force
+  }
   [System.IO.File]::WriteAllText((Join-Path $dist 'cli.js'), "setInterval(function(){}, 1000);`r`n", (New-Object System.Text.UTF8Encoding($false)))
 }
 
@@ -242,7 +364,8 @@ function New-Catalog([string]$Path, [string]$Version, [string]$Sha, [long]$Size)
 function Invoke-Applier([string]$InstallDir, [string[]]$Args) {
   $ps = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
   $all = @('-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', $Applier, '-InstallDir', $InstallDir) + $Args
-  $p = Start-Process -FilePath $ps -ArgumentList $all -NoNewWindow -PassThru -Wait
+  $p = Start-Process -FilePath $ps -ArgumentList $all -NoNewWindow -PassThru
+  $null = Wait-Bounded -Process $p
   $updateDir = Join-Path $InstallDir '.auto-update'
   $outcome = $null
   $outcomePath = Join-Path $updateDir 'outcome.json'
@@ -269,15 +392,18 @@ function Invoke-Applier([string]$InstallDir, [string[]]$Args) {
 }
 
 function Publish-Payload([string]$TreeDir, [string]$Name) {
+  $t0 = Get-Date
   $zip = Join-Path $Www $Name
   if (Test-Path -LiteralPath $zip) { Remove-Item -LiteralPath $zip -Force }
   Add-Type -AssemblyName System.IO.Compression.FileSystem
   [System.IO.Compression.ZipFile]::CreateFromDirectory($TreeDir, $zip, [System.IO.Compression.CompressionLevel]::Fastest, $false)
-  return [pscustomobject]@{
+  $out = [pscustomobject]@{
     Path  = $zip
     Bytes = (Get-Item -LiteralPath $zip).Length
     Sha   = (Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash.ToLowerInvariant()
   }
+  Say ("zipped $Name : {0:N1} MB in {1:N1}s" -f ($out.Bytes / 1MB), ((Get-Date) - $t0).TotalSeconds)
+  return $out
 }
 
 function Get-Shape([string]$Name) {
@@ -318,15 +444,18 @@ try {
   New-Item -ItemType Directory -Force -Path $Root, $Www | Out-Null
   Start-Origin
 
+  Say 'minting two throwaway code-signing certificates'
   $goodCert = New-HarnessCert 'Trillboards CI Update Harness'
   $otherCert = New-HarnessCert 'Definitely Not Trillboards'
   $signer = 'Trillboards CI Update Harness'
   $version = '9.9.9'
+  Say 'certificates ready'
 
   $payloadTree = Join-Path $Root 'payload-src'
   New-PayloadTree -Dest $payloadTree -SignCert $goodCert
   $good = Publish-Payload $payloadTree 'payload.zip'
-  Say ("payload: {0} bytes, sha {1}" -f $good.Bytes, $good.Sha)
+  Say ("reference payload: {0} bytes, sha {1}" -f $good.Bytes, $good.Sha)
+  Assert-WithinDeadline 'building the reference payload'
 
   $catalogGood = Join-Path $Www 'catalog-good.ps1'
   New-Catalog $catalogGood $version $good.Sha $good.Bytes
@@ -336,6 +465,7 @@ try {
 
   # ---- A: HAPPY PATH. The control for every arm below it -------------------
   Say '--- arm A: happy path (the shared control) ---'
+  Assert-WithinDeadline 'arm A: happy path (the shared control)'
   $installA = Join-Path $Root 'install-a'
   New-InstallTree $installA
   $a = Invoke-Applier $installA @('-Stage', '-UpdateUrl', $urlZip, '-CatalogUrl', "$BaseUrl/catalog-good.ps1",
@@ -349,6 +479,7 @@ try {
 
   # ---- B: WRONG HASH -------------------------------------------------------
   Say '--- arm B: the payload does not match the signed hash ---'
+  Assert-WithinDeadline 'arm B: the payload does not match the signed hash'
   $tampered = Join-Path $Www 'payload-tampered.zip'
   Copy-Item -LiteralPath $good.Path -Destination $tampered -Force
   $bytes = [System.IO.File]::ReadAllBytes($tampered)
@@ -366,6 +497,7 @@ try {
 
   # ---- C: SHORT BODY -------------------------------------------------------
   Say '--- arm C: the download is short (what a disk filling mid-download looks like) ---'
+  Assert-WithinDeadline 'arm C: the download is short (what a disk filling mid-download looks like)'
   $short = Join-Path $Www 'payload-short.zip'
   # A real byte[] copy, not a PowerShell range slice: `$bytes[0..n]` boxes every
   # element into an Object[], which WriteAllBytes will not take and which is
@@ -385,6 +517,7 @@ try {
 
   # ---- D: UNSIGNED CATALOG -------------------------------------------------
   Say '--- arm D: the catalog is not signed at all ---'
+  Assert-WithinDeadline 'arm D: the catalog is not signed at all'
   $catalogUnsigned = Join-Path $Www 'catalog-unsigned.ps1'
   New-Catalog $catalogUnsigned $version $good.Sha $good.Bytes
   if ((Get-AuthenticodeSignature -LiteralPath $catalogUnsigned).Status -eq 'Valid') {
@@ -400,6 +533,7 @@ try {
 
   # ---- E: WRONG PUBLISHER (the sharpest control) ---------------------------
   Say '--- arm E: the catalog is VALIDLY signed, by somebody else ---'
+  Assert-WithinDeadline 'arm E: the catalog is VALIDLY signed, by somebody else'
   $catalogOther = Join-Path $Www 'catalog-other.ps1'
   New-Catalog $catalogOther $version $good.Sha $good.Bytes
   Sign-File $catalogOther $otherCert
@@ -417,6 +551,7 @@ try {
 
   # ---- F: SIGNED THEN TAMPERED --------------------------------------------
   Say '--- arm F: the catalog was signed, then edited ---'
+  Assert-WithinDeadline 'arm F: the catalog was signed, then edited'
   $catalogEdited = Join-Path $Www 'catalog-edited.ps1'
   Copy-Item -LiteralPath $catalogGood -Destination $catalogEdited -Force
   Add-Content -LiteralPath $catalogEdited -Value '# an edit after signing'
@@ -431,6 +566,7 @@ try {
 
   # ---- G: DISK PREFLIGHT ---------------------------------------------------
   Say '--- arm G: the declared payload does not fit on the volume ---'
+  Assert-WithinDeadline 'arm G: the declared payload does not fit on the volume'
   $huge = Join-Path $Www 'catalog-huge.ps1'
   New-Catalog $huge $version $good.Sha 900000000000
   Sign-File $huge $goodCert
@@ -445,6 +581,7 @@ try {
 
   # ---- H: UNSIGNED SCRIPT INSIDE THE PAYLOAD -------------------------------
   Say '--- arm H: the payload contains an unsigned script ---'
+  Assert-WithinDeadline 'arm H: the payload contains an unsigned script'
   $rogueTree = Join-Path $Root 'payload-rogue'
   New-PayloadTree -Dest $rogueTree -SignCert $goodCert -WithUnsignedScript
   $rogue = Publish-Payload $rogueTree 'payload-rogue.zip'
@@ -468,9 +605,9 @@ try {
     )) {
     Say "--- arm $($arm.Name): commit over a RUNNING connector, with a payload that would re-register logon-only ---"
     $installJ = Join-Path $Root "install-$($arm.Name)"
-    New-InstallTree $installJ
+    New-InstallTree $installJ -RealNode
     $downTree = Join-Path $Root "payload-down-$($arm.Name)"
-    New-PayloadTree -Dest $downTree -SignCert $goodCert -LogonOnlyRegisterTask
+    New-PayloadTree -Dest $downTree -SignCert $goodCert -LogonOnlyRegisterTask -RealNode
     $down = Publish-Payload $downTree "payload-down-$($arm.Name).zip"
     $catDown = Join-Path $Www "catalog-down-$($arm.Name).ps1"
     New-Catalog $catDown $version $down.Sha $down.Bytes
@@ -521,8 +658,10 @@ try {
   # ---- K: the would-downgrade preflight, from an UNELEVATED caller ---------
   if ($SkipUnelevatedArm) {
     Say '--- arm K SKIPPED by request ---'
+  Assert-WithinDeadline 'arm K SKIPPED by request'
   } else {
     Say '--- arm K: an unelevated caller must REFUSE rather than downgrade ---'
+  Assert-WithinDeadline 'arm K: an unelevated caller must REFUSE rather than downgrade'
     $installK = Join-Path $Root 'install-k'
     New-InstallTree $installK
     $downTree = Join-Path $Root 'payload-k'
@@ -563,8 +702,9 @@ try {
       $ps = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
       # Materialise the profile once, so the run under test is not measuring
       # first-logon profile creation.
-      Start-Process -FilePath $env:ComSpec -ArgumentList '/c', 'exit' -Credential $cred -LoadUserProfile `
-        -WorkingDirectory 'C:\' -Wait -ErrorAction Stop
+      $warm = Start-Process -FilePath $env:ComSpec -ArgumentList '/c', 'exit' -Credential $cred -LoadUserProfile `
+        -WorkingDirectory 'C:\' -PassThru -ErrorAction Stop
+      $null = Wait-Bounded -Process $warm -Phase 'arm K: materialising the local profile'
 
       # Drive the COPY inside the install tree, not the one in the repo
       # workspace: the ACL above covers the install tree, and the runner's
@@ -572,10 +712,11 @@ try {
       $applierCopy = Join-Path $installK 'bin\apply-update.ps1'
       $outK = Join-Path $Root 'k-stdout.txt'
       $errK = Join-Path $Root 'k-stderr.txt'
-      $null = Start-Process -FilePath $ps -Credential $cred -LoadUserProfile -WorkingDirectory 'C:\' -PassThru -Wait `
+      $pk = Start-Process -FilePath $ps -Credential $cred -LoadUserProfile -WorkingDirectory 'C:\' -PassThru `
         -RedirectStandardOutput $outK -RedirectStandardError $errK `
         -ArgumentList @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $applierCopy,
         '-InstallDir', $installK, '-Commit', '-ExpectedVersion', $version, '-CurrentVersion', '9.9.8')
+      $null = Wait-Bounded -Process $pk
       foreach ($f in @($outK, $errK)) {
         if (Test-Path -LiteralPath $f) {
           $t = Get-Content -Raw -LiteralPath $f

package/deploy/windows/enroll-connector.ps1

@@ -0,0 +1,169 @@
+<#
+  enroll-connector.ps1 - UNATTENDED provisioning step for an MDM/Intune/SCCM
+  deployment. Invoked by installer.nsi when /ENROLLMENT_TOKEN= was supplied.
+
+  WHAT IT DOES
+    1. Writes the fleet enrollment credential to $InstallDir\trillboards.enrollment
+       with an ACL that grants the installing user ONLY (inheritance disabled),
+       because a plain %LOCALAPPDATA% file inherits whatever the parent grants
+       and this is the one credential in the package that can enroll machines.
+    2. Runs `trillboards-edge enroll`, which exchanges it for THIS machine's own
+       credential, writes that into trillboards.config.json, and DELETES the
+       enrollment file.
+    3. Deletes the file itself if the CLI could not (belt and braces - a fleet
+       credential left on 200 store PCs is the failure this whole design exists
+       to prevent).
+
+  EXIT CODES - these are the installer's, and they are deliberately NOT fatal to
+  the install:
+    0  enrolled, or already enrolled (a re-push is idempotent and free)
+    1  the credential was rejected: expired, revoked, or every enrollment it was
+       issued for is already used. A human must issue a new one.
+    6  network/server failure. The credential was NOT spent; the scheduled task
+       retries on the next logon.
+
+  A failed enrollment leaves a correctly INSTALLED connector that is simply not
+  yet provisioned, which is recoverable by re-running this script or by the
+  ordinary interactive setup. Aborting the whole install instead would leave the
+  machine with nothing and no way to retry.
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][string]$InstallDir,
+  [Parameter(Mandatory = $true)][string]$EnrollmentToken,
+  [string]$SiteLabel = "",
+  [string]$ApiBase = "",
+  # Optional recorder credentials. Passed straight through to the CLI and never
+  # written to disk or to the log - only their PRESENCE is logged.
+  [string]$NvrUser = "",
+  [string]$NvrPass = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+$logDir = Join-Path $env:LOCALAPPDATA "Trillboards\logs"
+New-Item -ItemType Directory -Force -Path $logDir | Out-Null
+$logPath = Join-Path $logDir "enroll.log"
+
+function Write-Log([string]$Message) {
+  # NEVER log the token. Only its shape, so support can match it to a portal row
+  # without the log becoming a credential store.
+  $stamp = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+  Add-Content -Path $logPath -Value "[$stamp] $Message"
+}
+
+$enrollmentFile = Join-Path $InstallDir "trillboards.enrollment"
+$configPath = Join-Path $InstallDir "trillboards.config.json"
+
+function Remove-EnrollmentFile {
+  if (Test-Path $enrollmentFile) {
+    try {
+      Remove-Item -Force $enrollmentFile
+      Write-Log "enrollment file removed"
+    } catch {
+      Write-Log "WARNING: could not remove enrollment file: $($_.Exception.Message)"
+    }
+  }
+}
+
+try {
+  if ([string]::IsNullOrWhiteSpace($EnrollmentToken)) {
+    Write-Log "no enrollment token supplied; nothing to do"
+    exit 0
+  }
+
+  $tokenShape = if ($EnrollmentToken.Length -gt 11) {
+    "$($EnrollmentToken.Substring(0,7))...$($EnrollmentToken.Substring($EnrollmentToken.Length-4))"
+  } else { "(short)" }
+  $credState = if ([string]::IsNullOrWhiteSpace($NvrUser)) { "absent" } else { "supplied" }
+  Write-Log "starting unattended enrollment (credential $tokenShape, site '$SiteLabel', recorder credentials $credState)"
+
+  New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
+  # -NoNewline so the CLI's trim() sees exactly the token; ASCII because the key
+  # alphabet is hex and a BOM would corrupt the first character.
+  [System.IO.File]::WriteAllText($enrollmentFile, $EnrollmentToken, [System.Text.UTF8Encoding]::new($false))
+
+  # Owner-only ACL with inheritance broken. %LOCALAPPDATA% is already per-user,
+  # but this file is the one credential that can enroll further machines, so it
+  # does not ride on a directory default that a group policy may widen.
+  try {
+    $acl = Get-Acl $enrollmentFile
+    $acl.SetAccessRuleProtection($true, $false)   # break inheritance, drop inherited ACEs
+    $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
+      $me, "FullControl", "None", "None", "Allow")
+    $acl.SetAccessRule($rule)
+    Set-Acl -Path $enrollmentFile -AclObject $acl
+    Write-Log "enrollment file ACL set to owner-only"
+  } catch {
+    # Non-fatal: the file is deleted seconds from now. Losing the ACL is worth a
+    # log line, not a failed rollout.
+    Write-Log "WARNING: could not tighten enrollment file ACL: $($_.Exception.Message)"
+  }
+
+  $node = Join-Path $InstallDir "bin\node.exe"
+  $cli = Join-Path $InstallDir "lib\edge-sdk\dist\cli.js"
+  if (-not (Test-Path $node) -or -not (Test-Path $cli)) {
+    # Retryable and the credential is UNSPENT - keep it so the next-logon retry
+    # can use it once the install finishes laying the tree down.
+    Write-Log "ERROR: connector is not installed at $InstallDir (retryable, credential preserved)"
+    exit 6
+  }
+
+  $cliArgs = @($cli, "enroll", "--config", $configPath, "--enrollment-file", $enrollmentFile)
+  if (-not [string]::IsNullOrWhiteSpace($SiteLabel)) { $cliArgs += @("--site", $SiteLabel) }
+  if (-not [string]::IsNullOrWhiteSpace($ApiBase)) { $cliArgs += @("--api-base", $ApiBase) }
+  if (-not [string]::IsNullOrWhiteSpace($NvrUser)) { $cliArgs += @("--nvr-user", $NvrUser) }
+  if (-not [string]::IsNullOrWhiteSpace($NvrPass)) { $cliArgs += @("--nvr-pass", $NvrPass) }
+
+  $oldPath = $env:PATH
+  $oldNodePath = $env:NODE_PATH
+  try {
+    $env:PATH = "$(Join-Path $InstallDir 'bin');$oldPath"
+    $env:NODE_PATH = Join-Path $InstallDir "lib\node_modules"
+    $output = (& $node @cliArgs 2>&1 | Out-String)
+    $code = $LASTEXITCODE
+  } finally {
+    $env:PATH = $oldPath
+    $env:NODE_PATH = $oldNodePath
+  }
+
+  # The CLI never prints the credential (see maskConnectorKey), so its output is
+  # safe to log verbatim and is the only diagnostic a field failure leaves.
+  Write-Log "enroll exit=$code output=$($output.Trim())"
+
+  # DELETE ONLY ON A TERMINAL OUTCOME.
+  #
+  # The CLI already deletes the file itself on success. The dangerous case is a
+  # RETRYABLE failure: an unconditional delete here would destroy the only
+  # persisted copy of the fleet credential on a transient outage during install,
+  # leaving that store permanently unprovisioned with nothing to retry from - the
+  # opposite of what the exit code says. So the file survives exit 6 and the
+  # next-logon retry in run-connector.ps1 picks it up.
+  #
+  # It IS deleted on a credential REJECTION (exit 1), because that token can
+  # never enroll anything again and leaving a dead credential on disk is pure
+  # exposure.
+  switch ($code) {
+    0 { Remove-EnrollmentFile; Write-Log "enrollment complete, cameras registered"; exit 0 }
+    5 {
+      # Provisioned, but no feeds. The credential is SPENT, so the enrollment
+      # file is done - what is missing is recorder credentials, not a retry.
+      Remove-EnrollmentFile
+      Write-Log "enrolled, but NO camera feeds registered (recorder credentials absent or no recorder found)"
+      exit 5
+    }
+    1 { Remove-EnrollmentFile; Write-Log "enrollment credential REJECTED - a new one must be issued"; exit 1 }
+    4 { Remove-EnrollmentFile; Write-Log "no enrollment token was readable"; exit 1 }
+    default {
+      Write-Log "enrollment deferred (retryable) - credential PRESERVED for the next-logon retry"
+      exit 6
+    }
+  }
+} catch {
+  # An exception here is a local/environmental failure, not a rejected
+  # credential, so it is retryable and the token is preserved for the same
+  # reason as exit 6 above.
+  Write-Log "ERROR (retryable, credential preserved): $($_.Exception.Message)"
+  exit 6
+}