@trillboards/edge-sdk 0.2.21 → 0.2.25

package/deploy/macos/scripts/setup-litertlm.sh

@@ -168,6 +168,36 @@ if [ "$HOST_OS" = "Darwin" ] && [ "$HOST_ARCH" != "arm64" ]; then
   exit 0
 fi
 
+# 0b. Enterprise TLS + proxy for uv.
+#
+# uv ships bundled Mozilla roots and does NOT consult the macOS keychain, so on
+# a network that inspects TLS this step is the first thing that fails -- and it
+# fails with a message about local AI, which is the wrong cause. UV_SYSTEM_CERTS
+# switches it to the platform's native verifier; UV_NATIVE_TLS is the older,
+# deprecated-but-still-read name for the same setting, exported too because
+# `uv tool install` here is UNPINNED and the version that lands is whatever is
+# current that day. An unknown env var is ignored, so both are safe; a CLI flag
+# would fail outright on a version that does not have it.
+export UV_SYSTEM_CERTS=1
+export UV_NATIVE_TLS=1
+
+# The proxy half: uv reads only the environment, never the macOS system proxy
+# settings. Fill them in from scutil when the operator has not set them already.
+if [ -z "${HTTPS_PROXY:-}" ] && [ -z "${https_proxy:-}" ] && [ -z "${ALL_PROXY:-}" ]; then
+  _proxy_conf="$(/usr/sbin/scutil --proxy 2>/dev/null || true)"
+  _proxy_enabled="$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSEnable/ {print $3}')"
+  if [ "$_proxy_enabled" = "1" ]; then
+    _proxy_host="$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSProxy/ {print $3}')"
+    _proxy_port="$(printf '%s\n' "$_proxy_conf" | awk '/HTTPSPort/ {print $3}')"
+    if [ -n "$_proxy_host" ]; then
+      HTTPS_PROXY="http://$_proxy_host${_proxy_port:+:$_proxy_port}"
+      export HTTPS_PROXY
+      export HTTP_PROXY="$HTTPS_PROXY"
+      log "using this machine's configured proxy for local AI downloads: $HTTPS_PROXY"
+    fi
+  fi
+fi
+
 # 1. uv (PATH first; else official standalone installer, home-domain).
 export PATH="$LOCAL_BIN:$USER_HOME/.cargo/bin:$PATH"
 if ! command -v uv >/dev/null 2>&1; then

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/e2e/test-enterprise-trust-store.ps1

@@ -0,0 +1,341 @@
+<#
+  RUNTIME PROOF: the connector reads THIS MACHINE'S Windows certificate store,
+  and still refuses a certificate that store does not vouch for.
+
+  WHY THIS EXISTS
+  ---------------
+  Node ships its own Mozilla-derived root list and does not consult the Windows
+  store, so behind a TLS-inspecting corporate proxy the connector could not
+  reach the API at all -- on the repair install path, silently, in a background
+  process with no window. The Node-side fix reads the Root stores at runtime.
+  Everything about that fix is Windows-specific and the merge-gating CI lane is
+  Linux, so on Linux the store reader is exercised only through an injected
+  seam. This script is the half that is NOT a seam: it imports a throwaway
+  certificate into the REAL LocalMachine\Root store and measures what the REAL
+  shipped code does with it.
+
+  WHAT IT PROVES, AND THE CONTROL FOR EACH
+  ----------------------------------------
+    A. BEFORE the import, the connector REFUSES the inspecting proxy's
+       certificate.  <- the failing control. If this passes, the machine already
+                        trusted the root and every later assertion is vacuous.
+       It also asserts the store read returned SOMETHING and the request really
+       went through the proxy, so B cannot pass for the wrong reason.
+    B. AFTER the import, the SAME request succeeds. Only the store changed.
+    C. AFTER the import, a certificate from a DIFFERENT root is STILL refused.
+       This is the assertion `rejectUnauthorized:false` would fail, and it is
+       the whole reason B is not evidence of a security regression.
+    D. The store read is not blocked by execution policy: it keeps working under
+       a machine-scope AllSigned GPO, which is the estate this work targets.
+       (The reader uses `powershell -Command`, and execution policy governs
+       script FILES; a regression to `-File` would fail exactly here.)
+
+  It REQUIRES elevation, and it must import into LocalMachine\Root specifically.
+  CurrentUser\Root is writable by the signed-in user in the ACL sense, which is
+  exactly what makes it a trap: a write to a CurrentUser TRUST-ANCHOR store is
+  gated behind an interactive "you are about to install a certificate from a
+  certification authority" consent dialog. On a headless runner nobody can answer
+  it, so Import-Certificate BLOCKS rather than fails -- it hung 23 minutes and ate
+  the job's entire timeout on 2026-08-15, reporting neither pass nor fail.
+  LocalMachine\Root is gated by administrator rights instead of by a dialog, so it
+  is non-interactive. That costs nothing here: CASE D already sets a machine-scope
+  execution policy, so this script has always needed admin, and hosted
+  windows-latest is elevated. It is also the more faithful test -- an AD GPO
+  pushes an enterprise root to LocalMachine\Root, and the connector runs as a
+  service, which has no CurrentUser store of its own.
+  The reader consults both LocalMachine\Root and CurrentUser\Root.
+
+  Certificates live in Cert:\CurrentUser\My + a temp dir for the life of the run
+  and are removed in the finally block. Nothing is printed.
+#>
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..\..\..\..")).Path
+)
+
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
+
+$work = Join-Path $env:RUNNER_TEMP ("tb-trust-proof-" + [Guid]::NewGuid().ToString("N").Substring(0, 8))
+$sdkDir = Join-Path $RepoRoot "trillboards-edge-sdk\packages\edge-sdk"
+$TARGET_DNS = "api.trillboards.test"
+$minted = @()
+$trustedThumbprint = $null
+$policyChanged = $false
+# Prior MachinePolicy registry state, captured in CASE D and restored in finally.
+$polKeyExisted = $false
+$priorEnable = $null
+$priorPolicy = $null
+
+function Fail([string]$Message) {
+  Write-Host "FAIL: $Message"
+  exit 1
+}
+
+# New-SelfSignedCertificate is the native path here: no openssl on PATH is
+# required (Git for Windows ships one but does not put it on PATH on the hosted
+# images), and a -Signer chain is exactly the CA -> leaf shape we need.
+function New-ProofCa([string]$CommonName) {
+  $ca = New-SelfSignedCertificate `
+    -Type Custom `
+    -Subject "CN=$CommonName" `
+    -KeyExportPolicy Exportable `
+    -KeyUsage CertSign, CRLSign `
+    -TextExtension @("2.5.29.19={text}CA=true&pathlength=0") `
+    -CertStoreLocation "Cert:\CurrentUser\My" `
+    -NotAfter (Get-Date).AddHours(2)
+  $script:minted += $ca.Thumbprint
+  return $ca
+}
+
+function New-ProofLeaf($Ca, [string]$Dns) {
+  $leaf = New-SelfSignedCertificate `
+    -Type Custom `
+    -Subject "CN=$Dns" `
+    -DnsName $Dns `
+    -KeyExportPolicy Exportable `
+    -Signer $Ca `
+    -CertStoreLocation "Cert:\CurrentUser\My" `
+    -NotAfter (Get-Date).AddHours(2)
+  $script:minted += $leaf.Thumbprint
+  return $leaf
+}
+
+try {
+  New-Item -ItemType Directory -Force -Path $work | Out-Null
+
+  Write-Host "== Minting a throwaway inspection CA and one for the negative control =="
+  $ca = New-ProofCa -CommonName "Trillboards Windows Trust Proof CA"
+  $otherCa = New-ProofCa -CommonName "Trillboards Windows Trust Proof OTHER CA"
+  $leaf = New-ProofLeaf -Ca $ca -Dns $TARGET_DNS
+  $otherLeaf = New-ProofLeaf -Ca $otherCa -Dns $TARGET_DNS
+
+  $pfxPassword = ConvertTo-SecureString -String ([Guid]::NewGuid().ToString("N")) -AsPlainText -Force
+  $pfxPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
+    [Runtime.InteropServices.Marshal]::SecureStringToBSTR($pfxPassword))
+  $leafPfx = Join-Path $work "leaf.pfx"
+  $otherPfx = Join-Path $work "otherleaf.pfx"
+  $caCer = Join-Path $work "ca.cer"
+  Export-PfxCertificate -Cert $leaf -FilePath $leafPfx -Password $pfxPassword | Out-Null
+  Export-PfxCertificate -Cert $otherLeaf -FilePath $otherPfx -Password $pfxPassword | Out-Null
+  Export-Certificate -Cert $ca -FilePath $caCer -Type CERT | Out-Null
+
+  # The probe: an inspecting proxy plus the SHIPPED agent, driven from Node so
+  # that what is measured is the real dist/ build and not a re-implementation.
+  $probe = Join-Path $work "probe.js"
+  $probeBody = @'
+// Stands up a CONNECT proxy that terminates TLS itself (an inspection
+// appliance), points the SHIPPED EnterpriseHttpsAgent at it, and reports what
+// happened as one line of JSON. Trust anchors come from the REAL Windows store
+// via the shipped reader -- nothing is injected.
+const fs = require('fs');
+const net = require('net');
+const https = require('https');
+const sdk = require(process.argv[2]);
+
+const pfx = fs.readFileSync(process.argv[3]);
+const passphrase = process.argv[4];
+const TARGET = 'api.trillboards.test';
+
+const inspector = https.createServer({ pfx, passphrase }, (_req, res) => {
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end('{"ok":true}');
+});
+
+const proxy = net.createServer((socket) => {
+  socket.once('data', (chunk) => {
+    if (!chunk.toString('latin1').startsWith('CONNECT ')) { socket.end('HTTP/1.1 405\r\n\r\n'); return; }
+    socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+    inspector.emit('connection', socket);
+  });
+  socket.on('error', () => {});
+});
+
+proxy.listen(0, '127.0.0.1', () => {
+  const port = proxy.address().port;
+  process.env.HTTPS_PROXY = 'http://127.0.0.1:' + port;
+  // The REAL reader, against the REAL CurrentUser\Root + LocalMachine\Root.
+  sdk.resetEnterpriseNetworkCaches();
+  const posture = sdk.describeNetworkPosture('https://' + TARGET);
+  const agent = sdk.getEnterpriseAgent();
+  const done = (result) => {
+    console.log(JSON.stringify(Object.assign({
+      anchorCount: posture.trust.certs.length,
+      anchorSources: posture.trust.sources.map((s) => s.name),
+      anchorWarnings: posture.trust.warnings,
+      proxyUrl: posture.proxy.proxyUrl,
+    }, result)));
+    proxy.close(); inspector.close(); agent.destroy(); process.exit(0);
+  };
+  const req = https.request('https://' + TARGET + '/health/live', { agent, timeout: 10000 }, (res) => {
+    res.resume();
+    res.on('end', () => done({ outcome: 'connected', statusCode: res.statusCode }));
+  });
+  req.on('timeout', () => req.destroy(new Error('probe timed out')));
+  req.on('error', (err) => done({
+    outcome: 'refused',
+    code: err.code || null,
+    failureClass: sdk.classifyTransportError(err, {}).failureClass,
+  }));
+  req.end();
+});
+'@
+  Set-Content -LiteralPath $probe -Value $probeBody -Encoding Ascii
+
+  # Build from the MONOREPO root, not the package: edge-sdk requires its sibling
+  # workspaces at runtime, so a package-scoped build silently depends on some
+  # earlier step in this job having built them. Building all of them here means
+  # this script is correct on its own and cannot be broken by a step reorder.
+  Write-Host "== Building the SDK so the probe measures the shipped build =="
+  Push-Location (Join-Path $RepoRoot "trillboards-edge-sdk")
+  & npm run build 2>&1 | Out-Null
+  $buildExit = $LASTEXITCODE
+  Pop-Location
+  if ($buildExit -ne 0) { Fail "edge-sdk build failed (exit $buildExit)" }
+  $sdkEntry = Join-Path $sdkDir "dist\index.js"
+  if (-not (Test-Path -LiteralPath $sdkEntry)) { Fail "edge-sdk dist/index.js is missing after the build" }
+
+  function Invoke-Probe([string]$Pfx) {
+    $raw = & node $probe $sdkEntry $Pfx $pfxPlain
+    if ($LASTEXITCODE -ne 0) { throw "probe exited $LASTEXITCODE" }
+    return (($raw | Select-Object -Last 1) | ConvertFrom-Json)
+  }
+
+  # ---------------------------------------------------------------- CONTROL A
+  Write-Host ""
+  Write-Host "== CONTROL A: before the import, the inspection cert must be REFUSED =="
+  $before = Invoke-Probe -Pfx $leafPfx
+  Write-Host ("  anchors read from the machine store: {0}" -f $before.anchorCount)
+  Write-Host ("  sources: {0}" -f ($before.anchorSources -join ", "))
+  Write-Host ("  warnings: {0}" -f ($before.anchorWarnings -join "; "))
+  Write-Host ("  proxy in use: {0}" -f $before.proxyUrl)
+  Write-Host ("  outcome: {0} {1} {2}" -f $before.outcome, $before.code, $before.failureClass)
+  if ($before.outcome -ne "refused") {
+    Fail "the untrusted inspection certificate was ACCEPTED before the import -- this probe cannot prove anything"
+  }
+  if ($before.failureClass -ne "tls_untrusted_root") {
+    Fail "expected failureClass tls_untrusted_root before the import, got '$($before.failureClass)'"
+  }
+  # The reader must have actually run. A store read that silently returned
+  # nothing would make case B below pass for the wrong reason.
+  if ([int]$before.anchorCount -lt 1) {
+    # The warnings are printed above. They are the whole point: the first version
+    # of the reader came back empty here with nothing to say about why, which
+    # cost a full windows-latest cycle to diagnose. Anything that reaches this
+    # line without an actionable warning above it is a reader bug of its own.
+    Fail "the Windows trust store read returned NO certificates -- see the warnings above; the reader did not run"
+  }
+  if (-not ("$($before.proxyUrl)" -like "http://127.0.0.1:*")) {
+    Fail "the probe did not go through the proxy -- HTTPS_PROXY was not honoured"
+  }
+
+  # ---------------------------------------------------------------- CASE B
+  Write-Host ""
+  Write-Host "== CASE B: import the root into LocalMachine\Root and retry =="
+  # LocalMachine, NOT CurrentUser. A write to a CurrentUser trust-anchor store
+  # raises an interactive consent dialog, which on a headless runner never gets
+  # answered and hangs this script forever (see the header). LocalMachine\Root is
+  # admin-gated instead, and is where a GPO-pushed enterprise root actually lands.
+  $imported = Import-Certificate -FilePath $caCer -CertStoreLocation "Cert:\LocalMachine\Root"
+  $trustedThumbprint = $imported.Thumbprint
+  Write-Host "  imported into Cert:\LocalMachine\Root (thumbprint recorded for cleanup)"
+
+  $after = Invoke-Probe -Pfx $leafPfx
+  Write-Host ("  anchors read from the machine store: {0}" -f $after.anchorCount)
+  Write-Host ("  outcome: {0} {1} {2}" -f $after.outcome, $after.statusCode, $after.failureClass)
+  if ($after.outcome -ne "connected" -or [int]$after.statusCode -ne 200) {
+    Fail "the connector still could not reach the API after the root was trusted (outcome=$($after.outcome) class=$($after.failureClass))"
+  }
+  if ([int]$after.anchorCount -le [int]$before.anchorCount) {
+    Fail "the anchor count did not grow after the import -- the reader is not seeing LocalMachine\Root"
+  }
+
+  # ---------------------------------------------------------------- CASE C
+  Write-Host ""
+  Write-Host "== CASE C: a cert from a DIFFERENT root is still REFUSED =="
+  $foreign = Invoke-Probe -Pfx $otherPfx
+  Write-Host ("  outcome: {0} {1} {2}" -f $foreign.outcome, $foreign.code, $foreign.failureClass)
+  if ($foreign.outcome -ne "refused") {
+    Fail "a certificate that chains to NO trusted root was accepted -- verification has been weakened, which is worse than the bug this fixes"
+  }
+  if ($foreign.failureClass -ne "tls_untrusted_root") {
+    Fail "expected failureClass tls_untrusted_root for the foreign root, got '$($foreign.failureClass)'"
+  }
+
+  # ---------------------------------------------------------------- CASE D
+  Write-Host ""
+  Write-Host "== CASE D: the store read survives a machine-scope AllSigned GPO =="
+  # Set-ExecutionPolicy -Scope MachinePolicy is REFUSED by Windows on purpose
+  # ("Execution policies at the MachinePolicy or UserPolicy scopes must be set
+  # through Group Policy"), so the cmdlet cannot stage this arm at all. A real
+  # GPO does not call the cmdlet either -- it writes these registry values, and
+  # the policy scope is just their projection. Writing them directly IS the GPO,
+  # not a workaround for one.
+  #
+  # Only the Windows PowerShell 5.1 key is written, never the PowerShellCore
+  # one. 5.1 is the interpreter the reader shells out to (`powershell -Command`),
+  # so it is the one this arm is about, and leaving pwsh 7's policy alone means a
+  # cleanup that fails to run cannot take the rest of the job's pwsh steps down
+  # with it -- the failure mode the step's own post-check exists to catch.
+  $polKey = "HKLM:\SOFTWARE\Policies\Microsoft\Windows\PowerShell"
+  $polKeyExisted = Test-Path $polKey
+  if ($polKeyExisted) {
+    $priorEnable = (Get-ItemProperty -Path $polKey -Name EnableScripts -ErrorAction SilentlyContinue).EnableScripts
+    $priorPolicy = (Get-ItemProperty -Path $polKey -Name ExecutionPolicy -ErrorAction SilentlyContinue).ExecutionPolicy
+  }
+  New-Item -Path $polKey -Force | Out-Null
+  New-ItemProperty -Path $polKey -Name "EnableScripts" -Value 1 -PropertyType DWord -Force | Out-Null
+  New-ItemProperty -Path $polKey -Name "ExecutionPolicy" -Value "AllSigned" -PropertyType String -Force | Out-Null
+  $policyChanged = $true
+  # Read it back through the interpreter it governs, not through pwsh 7, which
+  # reads a different key and would report Undefined no matter what we staged.
+  $effective = (& powershell.exe -NoProfile -Command "Get-ExecutionPolicy -Scope MachinePolicy" | Select-Object -Last 1).ToString().Trim()
+  Write-Host ("  MachinePolicy (Windows PowerShell 5.1) is now: {0}" -f $effective)
+  if ("$effective" -ne "AllSigned") {
+    Fail "could not stage MachinePolicy=AllSigned, so this arm would be vacuous"
+  }
+  $underPolicy = Invoke-Probe -Pfx $leafPfx
+  Write-Host ("  anchors read under AllSigned: {0}" -f $underPolicy.anchorCount)
+  Write-Host ("  outcome: {0}" -f $underPolicy.outcome)
+  if ([int]$underPolicy.anchorCount -lt [int]$after.anchorCount) {
+    Fail "the trust-store read returned fewer certificates under AllSigned ($($underPolicy.anchorCount) vs $($after.anchorCount)) -- execution policy is blocking it"
+  }
+  if ($underPolicy.outcome -ne "connected") {
+    Fail "the connector could not reach the API under AllSigned (outcome=$($underPolicy.outcome))"
+  }
+
+  Write-Host ""
+  Write-Host "PASS: refused before the import, connected after it, still refuses a foreign root, and reads the store under AllSigned."
+  exit 0
+} catch {
+  Write-Host "FAIL: $_"
+  exit 1
+} finally {
+  if ($policyChanged) {
+    # Restore exactly what was there, rather than deleting: on a developer's
+    # domain-joined machine this key may be REAL policy, and clearing it would
+    # silently relax that machine's execution policy.
+    $polKey = "HKLM:\SOFTWARE\Policies\Microsoft\Windows\PowerShell"
+    if ($polKeyExisted) {
+      if ($null -ne $priorEnable) {
+        New-ItemProperty -Path $polKey -Name "EnableScripts" -Value $priorEnable -PropertyType DWord -Force -ErrorAction SilentlyContinue | Out-Null
+      } else {
+        Remove-ItemProperty -Path $polKey -Name "EnableScripts" -Force -ErrorAction SilentlyContinue
+      }
+      if ($null -ne $priorPolicy) {
+        New-ItemProperty -Path $polKey -Name "ExecutionPolicy" -Value $priorPolicy -PropertyType String -Force -ErrorAction SilentlyContinue | Out-Null
+      } else {
+        Remove-ItemProperty -Path $polKey -Name "ExecutionPolicy" -Force -ErrorAction SilentlyContinue
+      }
+    } else {
+      Remove-Item -Path $polKey -Recurse -Force -ErrorAction SilentlyContinue
+    }
+  }
+  if ($trustedThumbprint) {
+    Remove-Item -LiteralPath "Cert:\LocalMachine\Root\$trustedThumbprint" -Force -ErrorAction SilentlyContinue
+  }
+  foreach ($thumb in $minted) {
+    Remove-Item -LiteralPath "Cert:\CurrentUser\My\$thumb" -Force -ErrorAction SilentlyContinue
+  }
+  if (Test-Path -LiteralPath $work) { Remove-Item -Recurse -Force $work -ErrorAction SilentlyContinue }
+}

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
+}