@trillboards/edge-sdk 0.2.16 → 0.2.18

package/THIRD-PARTY-NOTICES.md

@@ -47,3 +47,54 @@ SOFTWARE.
 Frigate™ is a trademark of Frigate, Inc. Its use here is nominative — to
 identify the upstream project this code was ported from. Trillboards is not
 affiliated with, endorsed by, or sponsored by Frigate, Inc.
+
+---
+
+## FFmpeg
+
+The Windows and macOS connector installers bundle a prebuilt static
+`ffmpeg` binary. RTSP capture goes through it — `RTSPCameraProvider` spawns it
+per frame — so it is redistributed as part of the product, not merely used at
+build time.
+
+**Which binary.** The Windows x64 build pinned at
+`deploy/windows/build-windows.ps1` is
+`eugeneware/ffmpeg-static` release `b6.0`, asset `ffmpeg-win32-x64`, SHA-256
+`e9fd5e711debab9d680955fc1e38a2c1160fd280b144476cc3f62bc43ef49db1`. That
+project republishes upstream Windows x64 builds from
+[gyan.dev](https://www.gyan.dev/ffmpeg/builds/).
+
+**License: GPL v3.** Confirmed two independent ways rather than assumed. The
+upstream builder states "All builds are 64-bit, static and licensed as GPLv3",
+and the binary reports its own configuration as
+
+```
+--enable-gpl --enable-version3 --enable-static ... --enable-libx264
+--enable-libx265 --enable-libxvid --enable-libvidstab --enable-librubberband
+--enable-libvmaf --enable-libopencore-amrnb --enable-libopencore-amrwb
+--enable-libvo-amrwbenc ...
+```
+
+`--enable-gpl` plus `--enable-version3` makes the combined work GPL v3.
+`--enable-nonfree` is **absent**, so the build is redistributable; a `nonfree`
+build would not be, and swapping the pin for one would make shipping it
+unlawful. Check that flag before ever changing the pin.
+
+**Corresponding Source (GPL v3 §6).** Trillboards conveys this object code and
+will provide the complete Corresponding Source for the exact binary above, on
+any medium customarily used for software interchange, to anyone who asks at
+**legal@trillboards.com**, for as long as we offer spare parts or customer
+support for this product. The upstream sources are FFmpeg
+(<https://ffmpeg.org/download.html>, <https://git.ffmpeg.org/ffmpeg.git>) and
+the build recipe published by the builder above.
+
+**Our modification, stated plainly (GPL v3 §5(a)).** Trillboards redistributes
+this binary unmodified except for one thing: we Authenticode-sign it with our
+own code-signing certificate (publisher `Aethercorp Inc`) before bundling it.
+Upstream ships it unsigned, which makes it an EDR and antivirus false-positive
+magnet and the one unsigned executable in an otherwise fully signed bundle. The
+signature is appended to the PE certificate table; no byte of the program image
+is altered, its version and configuration strings are untouched, and it imposes
+no restriction on anyone — a recipient remains free to strip the signature,
+replace the binary, or rebuild it from the Corresponding Source above. Nothing
+in the product requires `bin\ffmpeg.exe` to be signed in order to run.

package/deploy/macos/build-macos-pkg.sh

@@ -37,11 +37,41 @@
 #                                     air-gapped CI)
 #
 # --universal builds ONE fat arm64+x86_64 .pkg (node + ffmpeg lipo'd from both
-# arches; bundled fsevents.node is already universal) that installs + runs on
-# every Mac. This is the RELEASE artifact: a browser can't reliably detect a
-# Mac's CPU arch (Safari reports "MacIntel" even on Apple Silicon), so the portal
-# cannot hand out an arch-specific download. --arch builds a single-arch .pkg
-# (faster, for local testing).
+# arches; bundled fsevents.node is already universal). --arch builds a
+# single-arch .pkg.
+#
+# THE RELEASE ARTIFACT IS `--arch arm64`, NOT `--universal`. This comment used to
+# say the opposite — that universal "installs + runs on every Mac" and "is the
+# RELEASE artifact" — and that sentence is why PR #12228 tried to switch the
+# release lane to it. Do not repeat that. A universal .pkg makes `node` and
+# `ffmpeg` fat, and changes nothing about the constraint that actually decides
+# this: `litert_lm_api` is published ONLY for `macosx_12_0_arm64`. There is no
+# macOS x86_64 build to lipo against, and the installed `liblitert-lm.dylib` is
+# arm64-thin. scripts/setup-litertlm.sh:151,156 already encodes that —
+#
+#     if [ "$HOST_OS" = "Darwin" ] && [ "$HOST_ARCH" != "arm64" ]; then
+#       [ "$REQUIRE_BUNDLED_MODEL" = "1" ] && fail "local AI requires Apple silicon"
+#
+# — and postinstall sets TRILLBOARDS_REQUIRE_BUNDLED_MODEL=1, so on an Intel Mac
+# that refusal is an abort, not a downgrade.
+#
+# The arm64-thin binaries in the shipped .pkg are therefore a SYMPTOM OF THE
+# CORRECT BUILD, not a defect. What the two options actually do on an Intel Mac:
+#
+#   --arch arm64 (today) : Installer.app refuses up front. Nothing is written.
+#   --universal          : the installer ACCEPTS, lays down 2.27 GB, then dies in
+#                          postinstall — and there is no uninstaller to clean up.
+#
+# Failing before the download beats failing after it. Ship universal only when
+# upstream ships an x86_64 litert-lm AND the arch gate above is relaxed in the
+# same change; the `macos-release-arch-lockstep` guard below fails the build if
+# those two ever disagree.
+#
+# The one true thing the old comment said, kept because it still binds: a browser
+# cannot reliably detect a Mac's CPU arch (Safari reports "MacIntel" even on
+# Apple Silicon), so the portal cannot hand out an arch-specific download. That
+# is an argument for ONE artifact at one URL — it is not an argument that the
+# artifact can run everywhere, and conflating those is the error above.
 #
 # ffmpeg: a pinned static darwin build (eugeneware/ffmpeg-static b6.0 — the same
 # upstream the ffmpeg-static npm package ships) is downloaded at build time and

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

@@ -32,6 +32,17 @@ HF_REPO="litert-community/gemma-4-E2B-it-litert-lm"
 SERVE_LABEL="com.trillboards.litertlm"
 SERVE_PORT="9379"
 LITERT_PYTHON="${LITERT_LM_PYTHON:-3.12}"
+# PINNED litert-lm. This is not hygiene — the accelerator is selected by posting
+# a `<model-id>,gpu` model id, upstream calls that syntax deprecated, and it has
+# already changed twice without any release of ours: 0.14.0 (2026-07-08) dropped
+# both the `,gpu` entry from `GET /v1/models` AND the parse (measured: 404), and
+# 0.15.0 restored the parse but never the entry. An unpinned `--upgrade` means a
+# customer's per-frame cost can change 1.7-6.6x on a reinstall we did not ship.
+# Keep in lockstep with deploy/windows/setup-litertlm.ps1, LiteRtVlmProvider's
+# LITERT_LM_PINNED_VERSION, and .github/contracts/litert-lm-tested-versions.json
+# — the `litert-lm-version-pin` guard fails CI if they diverge or if this version
+# has no measured entry in that contract.
+LITERT_LM_VERSION="${LITERT_LM_VERSION:-0.16.0}"
 REQUIRE_BUNDLED_MODEL="${TRILLBOARDS_REQUIRE_BUNDLED_MODEL:-0}"
 ALLOW_MODEL_DOWNLOAD="${TRILLBOARDS_ALLOW_MODEL_DOWNLOAD:-0}"
 # Customer packages stage the model here. A network fallback remains available
@@ -170,18 +181,32 @@ if ! command -v "$UV" >/dev/null 2>&1 && [ ! -x "$UV" ]; then
   log "ERROR: uv unavailable; cannot provision LiteRT-LM"; exit 0
 fi
 
-# 2. litert-lm CLI. Keep a healthy existing install, but actively repair a
-# broken one. Older connector versions could let uv bind the tool to Apple's
-# Python 3.9; current LiteRT-LM uses Python features introduced in 3.10 and then
-# crash-loops before serving. --force rebuilds that existing tool environment
-# with the explicit managed interpreter while --upgrade refreshes the package.
+# 2. litert-lm CLI. Keep a healthy existing install AT THE PINNED VERSION, but
+# actively repair a broken or drifted one. Older connector versions could let uv
+# bind the tool to Apple's Python 3.9; current LiteRT-LM uses Python features
+# introduced in 3.10 and then crash-loops before serving. --force rebuilds that
+# existing tool environment with the explicit managed interpreter.
+#
+# The version check is part of "healthy". A `list`-only health check kept every
+# machine on whatever it happened to install first — which is how the box this
+# was designed on stayed on 0.13.1 (where the `,gpu` entry is advertised) while
+# every customer install after 2026-07-08 got a build that omits it. The bug
+# reproduced on their hosts and on none of ours.
 LITERTLM="$LOCAL_BIN/litert-lm"
 [ -x "$LITERTLM" ] || LITERTLM="$(command -v litert-lm || echo "$LITERTLM")"
-if [ -x "$LITERTLM" ] && "$LITERTLM" list >/dev/null 2>&1; then
-  log "litert-lm CLI is healthy — keeping current install"
+INSTALLED_LITERT_VERSION=""
+if [ -x "$LITERTLM" ]; then
+  INSTALLED_LITERT_VERSION="$("$LITERTLM" --version 2>/dev/null | tr -d '\r' | awk '{print $NF}')"
+fi
+if [ -x "$LITERTLM" ] && [ "$INSTALLED_LITERT_VERSION" = "$LITERT_LM_VERSION" ] \
+  && "$LITERTLM" list >/dev/null 2>&1; then
+  log "litert-lm CLI is healthy at pinned $LITERT_LM_VERSION — keeping current install"
 else
-  log "installing/repairing litert-lm with uv-managed Python $LITERT_PYTHON"
-  if ! "$UV" tool install --python "$LITERT_PYTHON" --managed-python --upgrade --force litert-lm >>"$LOG" 2>&1; then
+  if [ -n "$INSTALLED_LITERT_VERSION" ] && [ "$INSTALLED_LITERT_VERSION" != "$LITERT_LM_VERSION" ]; then
+    log "litert-lm $INSTALLED_LITERT_VERSION differs from pinned $LITERT_LM_VERSION — reinstalling"
+  fi
+  log "installing/repairing litert-lm==$LITERT_LM_VERSION with uv-managed Python $LITERT_PYTHON"
+  if ! "$UV" tool install --python "$LITERT_PYTHON" --managed-python --force "litert-lm==$LITERT_LM_VERSION" >>"$LOG" 2>&1; then
     [ "$REQUIRE_BUNDLED_MODEL" = "1" ] && fail "litert-lm install/repair failed"
     log "ERROR: litert-lm install/repair failed; local AI will retry later"
     exit 0
@@ -193,7 +218,7 @@ else
     log "ERROR: litert-lm remains unhealthy after repair; local AI will retry later"
     exit 0
   fi
-  log "litert-lm CLI repaired successfully"
+  log "litert-lm CLI repaired successfully at $("$LITERTLM" --version 2>/dev/null | awk '{print $NF}')"
 fi
 
 # 3. Model - import the verified bundled file. Idempotent: skip entirely if

package/deploy/windows/README.md

@@ -19,7 +19,11 @@ bin\trillboards-pair.cmd     hidden setup engine used by the setup window
 bin\trillboards-hidden-run.vbs  runs a helper with NO console (never use cmd's
                              `start`: it allocates a visible console before the
                              child can hide itself)
-bin\register-task.ps1        registers the logon Scheduled Task
+bin\register-task.ps1        registers the background Scheduled Task. Tries
+                             S4U + boot trigger first (runs with NOBODY logged
+                             on), and steps down one capability at a time to a
+                             repeating trigger and then an interactive
+                             principal, so a machine is never left with no task
 bin\stop-existing.ps1        DISABLES the task, stops this install's processes,
                              and proves bin\node.exe is unlocked before a swap
 bin\ensure-sensing.ps1       re-arms the task (register/enable/start) — closing
@@ -40,13 +44,22 @@ serves every Windows 10/11 — no per-arch builds.
 2. Run it. Production installers are Authenticode-signed with Azure Trusted
    Signing and the release workflow verifies the signature before publishing.
 3. Installer copies the connector, installs and verifies the included local AI,
-   registers the logon tasks, then opens **Trillboards CCTV Setup** without a
+   registers the startup tasks, then opens **Trillboards CCTV Setup** without a
    command window.
 4. Select **Start setup**. The app opens the Trillboards camera wizard, discovers
    local recorders, and validates each channel. Black, disconnected, and
    unreadable inputs are ignored; only working camera feeds become screens.
-5. Sensing starts with the already-installed local AI and restarts on every
-   logon; cloud inference is off by default.
+5. Sensing starts with the already-installed local AI; cloud inference is off
+   by default.
+6. Closing the setup window asks for **one UAC elevation**. That single prompt is
+   what makes sensing survive an unattended reboot, and it is a Windows rule
+   rather than a preference: an S4U principal performs a batch logon, and Task
+   Scheduler grants `SeBatchLogonRight` only when the caller is an administrator
+   (boot triggers are Administrators-only for the same reason). Accepting it
+   registers both tasks S4U + at boot, so the connector comes back within ~30 s
+   of every restart with nobody signed in. Declining it — or installing under a
+   standard user, who is never prompted because they could not satisfy it — keeps
+   a working task that repeats every 5 minutes but still needs someone logged on.
 
 ## Build (CI: `release-connector-windows.yml`, runs on `windows-latest`)
 

package/deploy/windows/build-windows.ps1

@@ -35,6 +35,15 @@
 .PARAMETER NodeVersion   Pinned Node runtime (default v22.22.0, matches macOS).
 .PARAMETER Offline       Skip downloads; copy the host node/ffmpeg (air-gapped CI).
 .PARAMETER SkipNsis      Stage only; do not compile the NSIS .exe (for unit checks).
+.PARAMETER FfmpegPath    Stage THIS ffmpeg.exe instead of downloading one. The
+                         release workflow fetches the pinned build, verifies its
+                         SHA-256, Authenticode-signs it, and passes the signed
+                         copy here — signing changes the bytes, so the hash gate
+                         has to run before it, not after.
+.PARAMETER PrintFfmpegPin
+                         Print "<download-url> <sha256>" and exit. The release
+                         workflow reads the pin from here rather than restating
+                         it, so the two can never drift.
 
 .OUTPUTS
   Prints the inner installer path on the last line:
@@ -44,7 +53,9 @@
 param(
   [string]$NodeVersion = "v22.22.0",
   [switch]$Offline,
-  [switch]$SkipNsis
+  [switch]$SkipNsis,
+  [string]$FfmpegPath = "",
+  [switch]$PrintFfmpegPin
 )
 
 $ErrorActionPreference = "Stop"
@@ -55,6 +66,9 @@ Set-StrictMode -Version Latest
 # verified after download; refuse to bundle an unverified binary.
 $FfmpegStaticTag = if ($env:FFMPEG_STATIC_TAG) { $env:FFMPEG_STATIC_TAG } else { "b6.0" }
 $FfmpegSha256Win = if ($env:FFMPEG_SHA256_WIN) { $env:FFMPEG_SHA256_WIN } else { "e9fd5e711debab9d680955fc1e38a2c1160fd280b144476cc3f62bc43ef49db1" }
+$FfmpegUrl = "https://github.com/eugeneware/ffmpeg-static/releases/download/$FfmpegStaticTag/ffmpeg-win32-x64"
+
+if ($PrintFfmpegPin) { Write-Output "$FfmpegUrl $FfmpegSha256Win"; exit 0 }
 
 # ─── Locate ourselves + the edge-sdk package root ─────────────────────────────
 $Here = Split-Path -Parent $MyInvocation.MyCommand.Path          # deploy\windows
@@ -152,8 +166,17 @@ if ($Offline) {
   $hostFf = (Get-Command ffmpeg -ErrorAction SilentlyContinue).Source
   if (-not $hostFf) { Die "offline mode: no host ffmpeg on PATH to copy." }
   Copy-Item -Force $hostFf $FfmpegBin
+} elseif ($FfmpegPath) {
+  # Supplied by the release workflow AFTER it verified the pinned SHA-256 and
+  # Authenticode-signed the binary. Re-checking the hash here would fail by
+  # construction: the signature is appended to the PE certificate table, so the
+  # signed file cannot hash to the unsigned pin. The pin still gates the build —
+  # just one step earlier, in the caller, against the bytes it downloaded.
+  if (-not (Test-Path -LiteralPath $FfmpegPath)) { Die "-FfmpegPath does not exist: $FfmpegPath" }
+  Log "Staging supplied ffmpeg: $FfmpegPath"
+  Copy-Item -Force -LiteralPath $FfmpegPath -Destination $FfmpegBin
 } else {
-  $url = "https://github.com/eugeneware/ffmpeg-static/releases/download/$FfmpegStaticTag/ffmpeg-win32-x64"
+  $url = $FfmpegUrl
   Log "Downloading pinned static ffmpeg: $url"
   Invoke-WebRequest -Uri $url -OutFile "$Scratch\ffmpeg.exe" -UseBasicParsing
   $actual = (Get-FileHash -Algorithm SHA256 "$Scratch\ffmpeg.exe").Hash.ToLower()

package/deploy/windows/ci/list-shipped-scripts.ps1

@@ -0,0 +1,58 @@
+<#
+.SYNOPSIS
+  Emit the scripts that actually ship inside the connector installer, DERIVED
+  from build-windows.ps1 rather than restated.
+
+.DESCRIPTION
+  "What ships" is decided by the `Copy-Item -Force "$Here\<file>"
+  "$Payload\bin\..."` calls in build-windows.ps1 - nothing else. A hand-kept
+  list beside it is a list that goes stale the first time someone adds a script
+  and forgets, and the failure is silent: the new file ships unsigned and only a
+  customer under GPO AllSigned finds out.
+
+  Consumers: the release workflow (which files to Authenticode-sign) and the
+  AllSigned enforcement harness (which files to prove).
+
+  Note deploy/windows/install-service.ps1 is deliberately absent: it is the
+  legacy service path, is not copied into the payload, and does not ship.
+
+.PARAMETER Kind
+  ps1 | vbs | cmd | signable (ps1 + vbs) | all
+
+.PARAMETER AbsolutePath
+  Emit full paths into deploy/windows instead of bare file names.
+#>
+[CmdletBinding()]
+param(
+  [ValidateSet('ps1', 'vbs', 'cmd', 'signable', 'all')][string]$Kind = 'all',
+  [switch]$AbsolutePath
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+$windowsDir = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$build = Join-Path $windowsDir 'build-windows.ps1'
+if (-not (Test-Path -LiteralPath $build)) { throw "build-windows.ps1 not found next to $PSScriptRoot" }
+
+$text = [IO.File]::ReadAllText($build)
+$matched = [regex]::Matches($text, 'Copy-Item\s+-Force\s+"\$Here\\([^"\\]+)"\s+"\$Payload\\bin\\')
+$names = @($matched | ForEach-Object { $_.Groups[1].Value } | Select-Object -Unique)
+
+# Derivation floor. If the Copy-Item shape in build-windows.ps1 ever changes,
+# this fails loudly here instead of silently signing nothing downstream.
+if ($names.Count -lt 12) {
+  throw "only $($names.Count) staged script(s) derived from build-windows.ps1 - the Copy-Item pattern changed; fix this derivation before trusting any signing step"
+}
+
+$selected = switch ($Kind) {
+  'ps1' { $names | Where-Object { $_ -like '*.ps1' } }
+  'vbs' { $names | Where-Object { $_ -like '*.vbs' } }
+  'cmd' { $names | Where-Object { $_ -like '*.cmd' } }
+  'signable' { $names | Where-Object { $_ -like '*.ps1' -or $_ -like '*.vbs' } }
+  default { $names }
+}
+
+foreach ($n in ($selected | Sort-Object)) {
+  if ($AbsolutePath) { Write-Output (Join-Path $windowsDir $n) } else { Write-Output $n }
+}

package/deploy/windows/ci/tb-canary.ps1

@@ -0,0 +1,18 @@
+# tb-canary.ps1 - CI only. Never staged into the installer payload.
+#
+# The AllSigned enforcement proof needs something it can actually RUN and watch
+# be blocked or admitted. The shipped scripts stop scheduled tasks and move
+# install trees, so they are proved through PowerShell's policy gate without
+# being executed; this stands in for them at execution time, and the release
+# workflow signs it in the SAME Trusted Signing call as the shipped scripts so
+# it carries identical signature provenance.
+#
+# Keep it ASCII and keep it trivial: anything it does other than write a marker
+# would make a 'blocked' result ambiguous.
+# [CmdletBinding()] on purpose: it lets the harness validate its non-executing
+# policy probe against this same file, because an unknown named parameter then
+# fails to bind instead of falling through to $args and running the body.
+[CmdletBinding()]
+param([string]$MarkerPath = "")
+if ($MarkerPath) { [IO.File]::WriteAllText($MarkerPath, "ran") }
+exit 0

package/deploy/windows/ci/tb-canary.vbs

@@ -0,0 +1,17 @@
+Option Explicit
+
+' tb-canary.vbs - CI only. Never staged into the installer payload.
+'
+' The .vbs half of the AllSigned enforcement proof. WSH has its own gate
+' (TrustPolicy=2, "run only signed and trusted scripts"), which PowerShell's
+' execution policy does not cover, so the .vbs enforcement is measured
+' separately. Signed in the same Trusted Signing call as the shipped scripts.
+
+Dim fso, args, f
+Set args = WScript.Arguments
+If args.Count > 0 Then
+  Set fso = CreateObject("Scripting.FileSystemObject")
+  Set f = fso.CreateTextFile(args(0), True)
+  f.WriteLine "ran"
+  f.Close
+End If