fix(security): tighten watchdog overshoot, guard Windows path, assert live termination [DEVA11Y-484]

Addresses gaps found by stress-testing the guard rather than just asserting the
happy path:

- Measured overshoot: at a 200ms poll, bsdtar could write ~270-380MB past the cap
  on a fast disk before the watchdog tripped (the cap was far softer than the
  "200 MB" message implied). Tightened the poll to 50ms — a 10MB cap now peaks at
  ~34MB and a 2GB bomb is killed at ~224MB. Documented the cap as an explicit SOFT
  ceiling whose purpose is preventing disk *exhaustion*, not exact byte enforcement.
- Windows Expand-Archive path was completely unguarded. Added a platform-agnostic
  post-extraction footprint backstop in the common path (typecheckable on macOS)
  so Windows rejects + cleans up a bomb before the binary is used.
- Strengthened tests to assert the LIVE watchdog fires (bsdtar SIGTERM, status 15)
  and that peak disk stays bounded below the bomb size — previously the bomb tests
  would have passed even if only the post-extraction check worked (which would let
  a multi-GB bomb fill the disk).
- Added test_large_bomb.sh (opt-in via DEVA11Y_DEEP=1): proves a 2GB bomb is
  bounded to ~224MB. Kept out of the default CI run to keep it fast/bounded.
- README now documents the real limitations: soft cap + overshoot, Windows is
  post-hoc only, the Swift suite tests a mirror (not the compiled plugin) with the
  call sites typecheck-only, and locateExecutable's cap is defense-in-depth.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: maunilm

Plugins/BrowserStackAccessibilityLint/BrowserStackAccessibilityLint.swift

@@ -225,6 +225,15 @@ private struct BrowserStackCLIDownloader {
         try extractWithBsdtar(from: info.resolvedURL, into: versionDirectory)
         #endif
 
+        // Platform-agnostic backstop (DEVA11Y-484). The bsdtar paths already abort mid-stream
+        // via the watchdog; this also covers the Windows Expand-Archive path, which has no
+        // streaming guard — it can't bound peak disk during extraction, but it rejects and
+        // cleans up a bomb before the binary is ever used.
+        if let reason = footprintExceeded(at: versionDirectory, maxBytes: Self.maxDecompressedBytes, maxEntries: Self.maxArchiveEntries) {
+            try? fileManager.removeItem(at: versionDirectory)
+            forwardExit(code: 1, message: "BrowserStack CLI archive rejected: \(reason). Aborting to prevent disk exhaustion.")
+        }
+
         let locatedBinary = try locateExecutable(in: versionDirectory, preferredName: executableName)
         let finalBinaryURL: URL
         if locatedBinary.lastPathComponent == executableName {
@@ -714,9 +723,14 @@ func footprintExceeded(at directory: URL, maxBytes: Int64, maxEntries: Int) -> S
 }
 
 /// Starts a background watchdog that terminates `process` (bsdtar) if the decompressed
-/// footprint in `directory` exceeds the byte or entry ceiling. The watchdog bounds peak
-/// disk use during a large/slow bomb; callers MUST also run `footprintExceeded` once the
-/// process exits, to catch a fast bomb that finished within a single poll interval.
+/// footprint in `directory` exceeds the byte or entry ceiling.
+///
+/// This is a SOFT ceiling: bsdtar can write up to one poll interval's worth of data past
+/// the limit before it is killed, so peak disk use is roughly `maxBytes + (pollInterval ×
+/// disk write rate)`. The goal is to prevent disk *exhaustion* by a multi-GB/TB bomb, not
+/// to enforce an exact byte count. The interval is kept short to bound the overshoot.
+/// Callers MUST also run `footprintExceeded` once the process exits, to catch a fast bomb
+/// that finished within a single poll interval.
 func startExtractionWatchdog(on process: Process, directory: URL, maxBytes: Int64, maxEntries: Int) -> ExtractionLimitState {
     let state = ExtractionLimitState()
     let watchdog = Thread {
@@ -726,7 +740,7 @@ func startExtractionWatchdog(on process: Process, directory: URL, maxBytes: Int6
                 process.terminate()
                 break
             }
-            Thread.sleep(forTimeInterval: 0.2)
+            Thread.sleep(forTimeInterval: 0.05)
         }
     }
     watchdog.start()

scripts/test/README.md

@@ -45,6 +45,29 @@ directly. Instead:
 - `check_drift.sh` diffs the two and **fails if they diverge**, so the mirror can never
   silently rot. If you edit the guard, copy the block into both — the drift check enforces it.
 
+## Known limitations (read before trusting this blindly)
+
+- **The cap is soft, not exact.** The Swift watchdog polls the extraction directory
+  (every 50 ms) and kills `bsdtar` once the footprint crosses the limit, so peak disk use
+  is roughly `cap + (poll interval × disk write rate)`. Measured: a 200 MB cap peaks around
+  ~230–300 MB on a fast NVMe; a 2 GB bomb is killed at ~224 MB (see `test_large_bomb.sh`).
+  The goal is preventing disk *exhaustion* by a multi-GB/TB bomb — not enforcing an exact
+  byte count. The shell `-O | head -c` path, by contrast, is a hard byte cap.
+- **The Swift tests run a mirror, not the compiled plugin.** `check_drift.sh` guarantees the
+  guard *block* matches, but the harness has its own copies of the `extractRemote/extractLocal`
+  call sites, which are NOT drift-checked. A bug in how the plugin wires the guard into those
+  call sites would not be caught here (the plugin edits are typecheck-only). Eliminating this
+  needs the larger refactor of extracting the logic into an importable target.
+- **`locateExecutable`'s 10k-entry cap is not exercised by the harness** — the watchdog's
+  entry ceiling (which IS tested) is the primary defense; the `locateExecutable` cap is
+  secondary/defense-in-depth and currently typecheck-only.
+- **Windows protection is post-hoc only.** The macOS/Linux `bsdtar` paths bound peak disk
+  mid-stream via the watchdog. The Windows `Expand-Archive` path has no streaming guard; it
+  gets only the platform-agnostic post-extraction backstop (it rejects + cleans up a bomb
+  before the binary is used, but the bomb can momentarily expand to its full size on disk
+  first). Windows also can't run on the macOS CI image, so it is verified by typecheck only.
+  A streaming guard for Windows is a follow-up.
+
 ## Files
 
 | File | Purpose |

scripts/test/run_tests.sh

@@ -25,6 +25,9 @@ bash "$HERE/test_shell_extraction.sh" || rc=1
 echo; echo "▶ Swift plugin guard tests (via mirror harness)"
 bash "$HERE/test_swift_extraction.sh" || rc=1
 
+echo; echo "▶ Large-bomb deep test (opt-in: DEVA11Y_DEEP=1)"
+bash "$HERE/test_large_bomb.sh" || rc=1
+
 echo
 if [ "$rc" -eq 0 ]; then
   echo "✅ DEVA11Y-484 suite: ALL GREEN"

scripts/test/swift-harness/Sources/ExtractionHarness/Guard.swift

@@ -71,9 +71,14 @@ func footprintExceeded(at directory: URL, maxBytes: Int64, maxEntries: Int) -> S
 }
 
 /// Starts a background watchdog that terminates `process` (bsdtar) if the decompressed
-/// footprint in `directory` exceeds the byte or entry ceiling. The watchdog bounds peak
-/// disk use during a large/slow bomb; callers MUST also run `footprintExceeded` once the
-/// process exits, to catch a fast bomb that finished within a single poll interval.
+/// footprint in `directory` exceeds the byte or entry ceiling.
+///
+/// This is a SOFT ceiling: bsdtar can write up to one poll interval's worth of data past
+/// the limit before it is killed, so peak disk use is roughly `maxBytes + (pollInterval ×
+/// disk write rate)`. The goal is to prevent disk *exhaustion* by a multi-GB/TB bomb, not
+/// to enforce an exact byte count. The interval is kept short to bound the overshoot.
+/// Callers MUST also run `footprintExceeded` once the process exits, to catch a fast bomb
+/// that finished within a single poll interval.
 func startExtractionWatchdog(on process: Process, directory: URL, maxBytes: Int64, maxEntries: Int) -> ExtractionLimitState {
     let state = ExtractionLimitState()
     let watchdog = Thread {
@@ -83,7 +88,7 @@ func startExtractionWatchdog(on process: Process, directory: URL, maxBytes: Int6
                 process.terminate()
                 break
             }
-            Thread.sleep(forTimeInterval: 0.2)
+            Thread.sleep(forTimeInterval: 0.05)
         }
     }
     watchdog.start()

scripts/test/test_large_bomb.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# DEEP test (opt-in): proves the watchdog bounds peak disk for a bomb FAR larger than
+# the cap — the real disk-exhaustion scenario. Skipped by default because it writes/reads
+# a multi-GB archive; enable with DEVA11Y_DEEP=1. Blast radius is bounded: if the guard
+# regressed entirely, it writes the bomb's full size once (a few GB) then cleans up.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/assert.sh
+source "$HERE/lib/assert.sh"
+
+if [ "${DEVA11Y_DEEP:-0}" != "1" ]; then
+  echo "test_large_bomb: skipped (set DEVA11Y_DEEP=1 to run the multi-GB bomb test)"
+  exit 0
+fi
+
+MB=$((1024*1024))
+BOMB_MB=${BOMB_MB:-2048}        # bomb decompressed size
+CAP_MB=${CAP_MB:-200}           # production byte cap
+PEAK_BUDGET_MB=${PEAK_BUDGET_MB:-700}  # generous ceiling proving we stop far below the bomb
+
+echo "Building Swift harness..."
+( cd "$HERE/swift-harness" && swift build ) >/dev/null 2>&1 || { echo "harness build failed"; exit 1; }
+HARNESS="$(cd "$HERE/swift-harness" && swift build --show-bin-path)/ExtractionHarness"
+
+WORK="$(mktemp -d)"
+trap 'stop_server; rm -rf "$WORK"' EXIT
+echo "Generating ${BOMB_MB} MB bomb..."
+( cd "$WORK" && dd if=/dev/zero bs=1048576 count="$BOMB_MB" of=cli 2>/dev/null && bsdtar -czf bomb-big.tar.gz cli && rm cli )
+
+start_server "$WORK" || exit 1
+
+echo "── Large-bomb watchdog test (${BOMB_MB} MB bomb, ${CAP_MB} MB cap) ──"
+dest="$(mktemp -d "$WORK/dest.XXXX")"; rm -rf "$dest"
+OUT=$("$HARNESS" remote "$(url_for bomb-big.tar.gz)" "$dest" "$((CAP_MB*MB))" 10000 "$((100*MB))" 2>/dev/null)
+echo "  outcome: $OUT"
+peak_mb=$(( $(python3 -c 'import sys,json;print(json.load(sys.stdin)["bytes"])' <<<"$OUT") / MB ))
+status=$(python3 -c 'import sys,json;print(json.load(sys.stdin)["bsdtarStatus"])' <<<"$OUT")
+
+assert_eq "$(python3 -c 'import sys,json;print(json.load(sys.stdin)["exceeded"])' <<<"$OUT")" "True" "large bomb: flagged as exceeded"
+assert_eq "$status" "15" "large bomb: bsdtar SIGTERM'd mid-stream"
+assert_le "$peak_mb" "$PEAK_BUDGET_MB" "large bomb: peak disk (${peak_mb}MB) bounded far below bomb size (${BOMB_MB}MB)"
+assert_absent "$dest" "large bomb: extraction dir removed"
+
+summary

scripts/test/test_swift_extraction.sh

@@ -47,10 +47,16 @@ assert_eq "$(jget "$OUT" bsdtarStatus)" "0" "legit: bsdtar exits 0"
 if [ -f "$DEST/browserstack-cli" ]; then ok "legit: binary extracted"; else bad "legit: binary missing"; fi
 "$DEST/browserstack-cli" >/dev/null 2>&1; assert_status $? 0 "legit: extracted binary runs"
 
-# 2. Decompression bomb (remote), small byte cap: flagged, terminated, dir removed.
+# 2. Decompression bomb (remote), small byte cap: flagged, terminated mid-stream, removed.
+#    The 400 MB fixture is ~8x the 50 MB cap, so a working LIVE watchdog must SIGTERM
+#    bsdtar (status 15) well before it finishes — asserting that catches a regression
+#    where only the post-extraction check works (which would let a huge bomb fill the disk).
 run_remote "bomb.tar.gz" "$CAP_SMALL" "$ENTRIES"
 assert_eq "$(jget "$OUT" exceeded)" "True" "bomb: flagged as exceeded"
 assert_contains "$(jget "$OUT" reason)" "decompressed size" "bomb: reason cites size"
+assert_eq "$(jget "$OUT" bsdtarStatus)" "15" "bomb: bsdtar SIGTERM'd mid-stream (live watchdog fired)"
+bomb_peak_mb=$(( $(jget "$OUT" bytes) / MB ))
+assert_le "$bomb_peak_mb" 350 "bomb: peak disk bounded below the 400 MB fixture (=${bomb_peak_mb}MB)"
 assert_absent "$DEST" "bomb: extraction dir removed"
 
 # 3. Entry-count bomb (20k tiny files), generous byte cap: flagged on entries.