browser4-cli 4.13.18 → 4.13.19

package/scripts/install-browser4-cli.sh

@@ -55,11 +55,41 @@ SCRIPT_DIR=""
 # ----------------------------------------------
 
 say()    { if [[ "$SILENT" != true ]]; then echo -e "$*"; fi; }
+# Informational note for helpers whose stdout is captured by the caller --
+# anything these functions print on stdout ends up inside the captured value.
+note()   { if [[ "$SILENT" != true ]]; then echo -e "    [i] $*" >&2; fi; }
 step()   { say "  -> $*"; }
 ok()     { say "    [v] $*"; }
 warn()   { say "    [!] $*" >&2; }
 die()    { echo "ERROR: $*" >&2; exit 1; }
 
+# Validate the value that must follow an option.  A missing value and a value
+# that is really the next option are both rejected: `--version --dry-run` used
+# to install the literal tag "--dry-run" (and `--install-dir --silent` created
+# a directory called "--silent"), which fails much later with a confusing 404.
+# Runs in the current shell so `die` really stops the installer -- a `die`
+# inside `$( ... )` only kills the subshell and the install would continue.
+validate_value() {
+  local flag="$1" value="${2:-}"
+  if [[ -z "$value" ]]; then
+    die "$flag requires a value"
+  fi
+  if [[ "$value" == -* ]]; then
+    die "$flag requires a value (got '$value', which looks like another option)"
+  fi
+}
+
+# Release tags on GitHub are prefixed with "v" (v4.13.18).  Accepting a bare
+# "4.13.18" and fixing it up front is friendlier than a 404 from the CDN.
+normalize_tag() {
+  local tag="$1"
+  if [[ "$tag" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+    note "Using release tag 'v$tag' (release tags are prefixed with 'v')"
+    tag="v$tag"
+  fi
+  printf '%s' "$tag"
+}
+
 color_cyan='\033[0;36m'
 color_green='\033[0;32m'
 color_yellow='\033[0;33m'
@@ -157,13 +187,12 @@ EOF
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --version|-v)
-      shift; [[ -z "${1:-}" ]] && die "--version requires a value"
-      VERSION="$1"; shift ;;
+      shift; validate_value "--version" "${1:-}"; VERSION=$(normalize_tag "$1"); shift ;;
     --install-dir|-d)
-      shift; [[ -z "${1:-}" ]] && die "--install-dir requires a value"
-      INSTALL_DIR="$1"; shift ;;
+      shift; validate_value "--install-dir" "${1:-}"; INSTALL_DIR="$1"; shift ;;
     --source)
-      shift; [[ -z "${1:-}" ]] && die "--source requires a value"
+      shift
+      validate_value "--source" "${1:-}"
       if [[ "$1" != "github" && "$1" != "oss" ]]; then
         die "--source must be 'github' or 'oss'"
       fi
@@ -316,7 +345,7 @@ get_default_install_dir() {
 
 check_commands() {
   local missing=()
-  for cmd in curl mktemp stat awk grep ln mkdir chmod; do
+  for cmd in curl mktemp stat awk grep ln mkdir chmod od cp mv tail cat; do
     if ! command -v "$cmd" >/dev/null 2>&1; then
       missing+=("$cmd")
     fi
@@ -326,6 +355,21 @@ check_commands() {
   fi
 }
 
+# A downloaded file must really be a native executable, not an HTML error page
+# or a wrong-architecture body that happens to be large.  Magic bytes are the
+# cheapest check that needs no network and no published checksum file.
+verify_binary_magic() {
+  local path="$1"
+  local magic
+  magic=$(od -An -tx1 -N4 "$path" 2>/dev/null | tr -d ' \n')
+  case "$magic" in
+    7f454c46) return 0 ;;                                     # ELF (linux glibc/musl)
+    4d5a*) return 0 ;;                                        # PE / MZ (windows)
+    feedface|feedfacf|cefaedfe|cffaedfe|cafebabe) return 0 ;;  # Mach-O, incl. fat
+    *) return 1 ;;
+  esac
+}
+
 get_download_urls() {
   local binary_name="$1"
   local version_tag="$2"
@@ -374,8 +418,15 @@ download_file() {
   curl_stderr=$(mktemp)
   local http_code curl_exit
 
+  # Only GitHub needs (and only GitHub may receive) the token: the same header
+  # must never be sent to the Aliyun OSS mirror.
+  local -a auth_args=()
+  if [[ -n "${GITHUB_TOKEN:-}" ]] && [[ "$url" == https://github.com/* ]]; then
+    auth_args=(-H "Authorization: Bearer $GITHUB_TOKEN")
+  fi
+
   http_code=$(curl -sSfL -w "%{http_code}" -o "$dest" \
-    ${GITHUB_TOKEN:+-H "Authorization: Bearer $GITHUB_TOKEN"} \
+    ${auth_args[@]+"${auth_args[@]}"} \
     "$url" 2>"$curl_stderr")
   curl_exit=$?
 
@@ -398,6 +449,11 @@ download_file() {
 
     # Sanity check: binary must be > 100 KB
     if [[ "$size" -gt 102400 ]]; then
+      if ! verify_binary_magic "$dest"; then
+        warn "Downloaded file is not a native executable (bad magic bytes) -- refusing it"
+        rm -f "$dest"
+        return 1
+      fi
       local size_mb
       size_mb=$(awk "BEGIN { printf \"%.1f\", $size / 1048576 }")
       ok "Downloaded ${size_mb} MB"
@@ -439,7 +495,11 @@ add_to_shell_rc() {
     rc_file="$HOME/.profile"
   fi
 
-  if grep -qF "$dir" "$rc_file" 2>/dev/null; then
+  local path_line="export PATH=\"$dir:\$PATH\""
+
+  # Idempotency: only PATH assignment lines count, so an unrelated mention of the
+  # directory (a comment, another tool's variable) does not suppress the entry.
+  if grep -E '^[[:space:]]*(export[[:space:]]+)?PATH=' "$rc_file" 2>/dev/null | grep -qF "$dir"; then
     ok "PATH entry already in $rc_file"
     return
   fi
@@ -454,23 +514,25 @@ add_to_shell_rc() {
     fi
   fi
 
-  # Use a lock file to prevent concurrent append races (best-effort).
+  # Serialize concurrent installs when the platform has flock (Linux).  macOS
+  # ships without it, and waiting for a lock that can never be taken only made
+  # every install pause and print a bogus warning.
   local lock_file="${rc_file}.browser4-install.lock"
-  local lock_fd=9
-  # Wait up to 10 seconds for another install process to release the lock.
-  local waited=0
-  while ! (umask 0002 && command -v flock >/dev/null 2>&1 && flock -n 9 2>/dev/null); do
-    if [[ $waited -ge 10 ]]; then
-      warn "Could not acquire lock on ${rc_file} after 10s; appending anyway"
-      break
-    fi
-    sleep 0.5
-    waited=$((waited + 1))
-  done 9>"$lock_file"
+  if command -v flock >/dev/null 2>&1; then
+    local waited=0
+    while ! flock -n 9 2>/dev/null; do
+      if [[ $waited -ge 20 ]]; then
+        warn "Could not acquire lock on ${rc_file} after 10s; appending anyway"
+        break
+      fi
+      sleep 0.5
+      waited=$((waited + 1))
+    done 9>"$lock_file"
+  fi
 
   {
     echo "# browser4-cli"
-    echo "export PATH=\"$dir:\$PATH\""
+    echo "$path_line"
   } >> "$rc_file"
 
   # Clean up (flock auto-releases when fd 9 is closed)
@@ -511,7 +573,7 @@ create_symlinks() {
   local b4_exists=false
   local b4_is_ours=false
 
-  # Check in install dir first — anything here is ours
+  # Check in install dir first - anything here is ours
   if [[ -e "$short_path" ]] || [[ -L "$short_path" ]]; then
     b4_exists=true
     b4_is_ours=true
@@ -620,7 +682,6 @@ install_backend() {
 # ----------------------------------------------
 
 main() {
-  check_commands
   header
 
   # Locate ourselves on disk (only works when run as a file, not piped)
@@ -663,9 +724,9 @@ main() {
       step "Local binary:     not found alongside script"
     fi
 
-    # Check for already-installed binary
+    # Check for already-installed binary (honour an explicit --install-dir)
     local default_dir existing_path
-    default_dir=$(get_default_install_dir)
+    default_dir="${INSTALL_DIR:-$(get_default_install_dir)}"
     existing_path="${default_dir}/${binary_name}"
     if [[ -f "$existing_path" ]]; then
       step "Already installed: $existing_path"
@@ -690,6 +751,10 @@ main() {
   step "Platform:  $platform_key"
   step "Binary:    $binary_name"
 
+  # Everything below downloads, unpacks or writes: check the tooling now, so
+  # `--locate` still works on a box that has none of it.
+  check_commands
+
   # Install directory
   if [[ -z "$INSTALL_DIR" ]]; then
     INSTALL_DIR=$(get_default_install_dir)
@@ -699,10 +764,15 @@ main() {
 
   # Ensure install directory exists
   if [[ ! -d "$INSTALL_DIR" ]]; then
-    if [[ "$DRY_RUN" != true ]]; then
-      mkdir -p "$INSTALL_DIR"
+    if [[ -e "$INSTALL_DIR" ]]; then
+      die "Install path exists but is not a directory: $INSTALL_DIR"
+    fi
+    if [[ "$DRY_RUN" == true ]]; then
+      step "[DRY-RUN] Would create directory: $INSTALL_DIR"
+    else
+      mkdir -p "$INSTALL_DIR" || die "Could not create install directory: $INSTALL_DIR"
+      step "Created directory: $INSTALL_DIR"
     fi
-    step "Created directory: $INSTALL_DIR"
   fi
 
   local binary_path="${INSTALL_DIR}/${binary_name}"

package/scripts/tests/install-browser4-cli.tests.ps1

@@ -37,6 +37,21 @@ function Test($name, [ScriptBlock]$block) {
     }
 }
 
+# ── Harness self-test ──
+# An assertion that throws MUST be counted as a failure.  Without this check a
+# harness that silently swallows failures looks perfectly green, which is
+# exactly how this suite's PowerShell sibling (the bash one) stayed green while
+# running no assertions at all.
+$selfTestFail = $script:fail
+Write-Host "  (one deliberate FAIL follows -- the harness self-test)" -ForegroundColor DarkGray
+Test "__harness self-test (must be reported as a failure)" { throw "expected failure" }
+if ($script:fail -ne ($selfTestFail + 1)) {
+    Write-Host "  FATAL  the harness does not record failures -- aborting" -ForegroundColor Red
+    exit 1
+}
+$script:fail = $selfTestFail
+Write-Host "  OK    harness self-test (a throwing assertion is counted as a failure)" -ForegroundColor DarkGray
+
 function RunScript([string]$scriptArgs, [ref]$exitCode) {
     # Use -Command to control stderr redirect (2> path must come before script args,
     # which -File would pass as literal arguments to the script).
@@ -52,7 +67,15 @@ function RunScript([string]$scriptArgs, [ref]$exitCode) {
     $out = $proc.StandardOutput.ReadToEnd()
     $proc.WaitForExit()
     $exitCode.Value = $proc.ExitCode
-    $err = if (Test-Path $tmpErr) { Get-Content $tmpErr -Raw -ErrorAction SilentlyContinue; Remove-Item $tmpErr -Force -ErrorAction SilentlyContinue } else { "" }
+    # Never leave $err as AutomationNull: `$null -eq $err` is true for it, but
+    # `$err -notmatch 'x'` returns an empty array, which is falsey -- an
+    # assertion written that way can never fail.
+    $err = ""
+    if (Test-Path $tmpErr) {
+        $err = Get-Content $tmpErr -Raw -ErrorAction SilentlyContinue
+        Remove-Item $tmpErr -Force -ErrorAction SilentlyContinue
+    }
+    if ($null -eq $err) { $err = "" }
     return [PSCustomObject]@{ Output = $out; Error = $err; ExitCode = $proc.ExitCode }
 }
 
@@ -217,10 +240,24 @@ Test "-SkipLocal flag accepted" {
     if ($ec4 -ne 0) { throw "Exit code: $ec4, output: $($r4.Output)" }
 }
 
-Test "-Force rejected (replaced by -SkipIfInstalled)" {
-    $ec5 = 0; $r5 = RunScript -scriptArgs "-Force -DryRun" -exitCode ([ref]$ec5)
-    if ($r5.Error -notmatch 'Force') {
-        throw "-Force should be rejected, got: $($r5.Error)"
+Test "-Force overrides -SkipIfInstalled, and is a live parameter" {
+    $tmp = Join-Path ([System.IO.Path]::GetTempPath()) "b4-force-$([System.IO.Path]::GetRandomFileName())"
+    New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+    foreach ($n in @('browser4-cli-win32-x64.exe', 'browser4-cli-linux-x64', 'browser4-cli-darwin-arm64')) {
+        Set-Content -Path (Join-Path $tmp $n) -Value "dummy" -Encoding Ascii
+    }
+    try {
+        $ecA = 0; $rA = RunScript -scriptArgs "-SkipIfInstalled -DryRun -SkipBackend -AddToPath:`$false -InstallDir `"$tmp`"" -exitCode ([ref]$ecA)
+        if ($rA.Output -notmatch 'Binary already installed') {
+            throw "Expected the -SkipIfInstalled skip path, got: $($rA.Output)"
+        }
+        $ecB = 0; $rB = RunScript -scriptArgs "-SkipIfInstalled -Force -DryRun -SkipBackend -AddToPath:`$false -InstallDir `"$tmp`"" -exitCode ([ref]$ecB)
+        if ($ecB -ne 0) { throw "-Force must be accepted, exit code: $ecB" }
+        if ($rB.Output -match 'Binary already installed') {
+            throw "-Force must override -SkipIfInstalled, got: $($rB.Output)"
+        }
+    } finally {
+        Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
     }
 }
 
@@ -236,8 +273,8 @@ Test "-Source github accepted" {
 
 Test "-Source invalid rejected" {
     $ec8 = 0; $r8 = RunScript -scriptArgs "-Source invalid -DryRun" -exitCode ([ref]$ec8)
-    if ($r8.Error -notmatch 'Source|invalid|parameter') {
-        throw "-Source invalid should be rejected, got: $($r8.Error)"
+    if ($ec8 -eq 0) {
+        throw "-Source invalid must fail, output: $($r8.Output)"
     }
 }
 
@@ -246,9 +283,33 @@ Test "-Silent flag accepted" {
     if ($ec9 -ne 0) { throw "Exit code: $ec9, output: $($r9.Output)" }
 }
 
-Test "-Version flag accepted" {
-    $ec10 = 0; $r10 = RunScript -scriptArgs "-Version v4.11.0 -DryRun" -exitCode ([ref]$ec10)
+Test "-Version reaches the download URLs" {
+    $ec10 = 0; $r10 = RunScript -scriptArgs "-Version v4.11.0 -DryRun -AddToPath:`$false" -exitCode ([ref]$ec10)
     if ($ec10 -ne 0) { throw "Exit code: $ec10, output: $($r10.Output)" }
+    if ($r10.Output -notmatch 'releases/download/v4\.11\.0/') {
+        throw "The tag never reached the URLs: $($r10.Output)"
+    }
+}
+
+Test "-Version accepts a bare semver and prefixes it with v" {
+    $ec11 = 0; $r11 = RunScript -scriptArgs "-Version 4.11.0 -DryRun -AddToPath:`$false" -exitCode ([ref]$ec11)
+    if ($ec11 -ne 0) { throw "Exit code: $ec11, output: $($r11.Output)" }
+    if ($r11.Output -notmatch 'releases/download/v4\.11\.0/') {
+        throw "Bare semver was not normalised to v4.11.0: $($r11.Output)"
+    }
+}
+
+Test "-Version rejects a path-traversal tag" {
+    $ec12 = 0; $r12 = RunScript -scriptArgs "-Version ../../evil -DryRun" -exitCode ([ref]$ec12)
+    if ($ec12 -eq 0) { throw "Traversal tag must be rejected, output: $($r12.Output)" }
+}
+
+Test "-DryRun does not probe the installed CLI" {
+    $ec13 = 0; $r13 = RunScript -scriptArgs "-DryRun -AddToPath:`$false" -exitCode ([ref]$ec13)
+    if ($ec13 -ne 0) { throw "Exit code: $ec13, output: $($r13.Output)" }
+    if ($r13.Output -match 'Backend already installed') {
+        throw "-DryRun ran 'status' on the installed CLI: $($r13.Output)"
+    }
 }
 
 Write-Host ""
@@ -256,10 +317,25 @@ Write-Host ""
 # ── Functions via dot-source ──
 Write-Host "--- Functions ---" -ForegroundColor Cyan
 
-# Strip trailing Main call and dot-source for function-level tests
-$scriptContent = Get-Content $installScript -Raw
-$scriptContent = $scriptContent -replace '\r?\nMain\s*$', ''
-$scriptContent = $scriptContent -replace '\$ErrorActionPreference\s*=\s*"Stop"', ''
+# Strip the trailing `Main` call and dot-source for function-level tests.
+# Strip it by AST extent, never by regex: if a line is ever appended after
+# `Main`, a regex silently stops matching and this suite would perform a REAL
+# install and edit the user PATH.
+$installAst = [System.Management.Automation.Language.Parser]::ParseFile($installScript, [ref]$null, [ref]$null)
+$mainCall = @($installAst.FindAll({
+    param($node)
+    $node -is [System.Management.Automation.Language.CommandAst] -and
+    $node.GetCommandName() -eq 'Main' -and
+    $node.Extent.Text.Trim() -eq 'Main'
+}, $true)) | Select-Object -Last 1
+if (-not $mainCall) {
+    throw "Could not locate the top-level 'Main' invocation in $installScript -- refusing to dot-source the installer"
+}
+$allLines = Get-Content $installScript
+$scriptContent = ($allLines[0..($mainCall.Extent.StartLineNumber - 2)] -join "`n") -replace '\$ErrorActionPreference\s*=\s*"Stop"', ''
+if ($scriptContent -match '(?m)^\s*Main\s*$') {
+    throw "The stripped copy still invokes Main -- refusing to dot-source the installer"
+}
 $sb = [ScriptBlock]::Create($scriptContent)
 
 & {
@@ -313,6 +389,31 @@ $sb = [ScriptBlock]::Create($scriptContent)
         if ($result -ne $null) { throw "Expected null, got: $result" }
     }
 
+    Test "Find-LocalBinary finds a bundled binary and enforces the 100 KB gate" {
+        # The bundled-binary path is what a sideload install uses; it used to be
+        # untestable because the dot-sourced copy never had a usable ScriptDir.
+        $tmp = Join-Path ([System.IO.Path]::GetTempPath()) "b4-local-$([System.IO.Path]::GetRandomFileName())"
+        New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+        try {
+            $name = Get-BinaryName -PlatformKey (Get-PlatformKey)
+            [System.IO.File]::WriteAllBytes((Join-Path $tmp $name), (New-Object byte[] 204800))
+            $savedScriptDir = $ScriptDir
+            try {
+                $ScriptDir = $tmp
+                $found = Find-LocalBinary -BinaryName $name
+                if (-not $found) { throw "A 200 KB bundled binary was not found in $tmp" }
+                [System.IO.File]::WriteAllBytes((Join-Path $tmp 'browser4-cli-too-small'), (New-Object byte[] 10))
+                if (Find-LocalBinary -BinaryName 'browser4-cli-too-small') {
+                    throw "A 10-byte file passed the 100 KB gate"
+                }
+            } finally {
+                $ScriptDir = $savedScriptDir
+            }
+        } finally {
+            Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
+        }
+    }
+
     Test "Test-LocalBinary returns false for empty string" {
         if (Test-LocalBinary -Path "") { throw "Should be false" }
     }
@@ -331,9 +432,43 @@ $sb = [ScriptBlock]::Create($scriptContent)
         if ($action -ne "upgrade") { throw "Expected 'upgrade', got: $action" }
     }
 
-    Test "Get-BackendAction defaults to upgrade on empty status" {
+    Test "Get-BackendAction defaults to install on empty status" {
+        # An empty status means "no CLI answer" (fresh machine, or `status`
+        # failed).  Defaulting to upgrade would run `upgrade` on a machine that
+        # has nothing to upgrade.
         $action = Get-BackendAction -StatusOutput ""
-        if ($action -ne "upgrade") { throw "Expected 'upgrade', got: $action" }
+        if ($action -ne "install") { throw "Expected 'install', got: $action" }
+    }
+
+    Test "Test-BinaryMagic accepts ELF, PE and Mach-O" {
+        $tmp = [System.IO.Path]::GetTempFileName()
+        try {
+            $cases = @{
+                'elf'    = [byte[]]@(0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01)
+                'pe'     = [byte[]]@(0x4d, 0x5a, 0x90, 0x00, 0x03)
+                'macho'  = [byte[]]@(0xcf, 0xfa, 0xed, 0xfe, 0x07)
+            }
+            foreach ($name in $cases.Keys) {
+                [System.IO.File]::WriteAllBytes($tmp, $cases[$name])
+                if (-not (Test-BinaryMagic -Path $tmp)) { throw "Rejected a valid $name header" }
+            }
+        } finally {
+            Remove-Item $tmp -Force -ErrorAction SilentlyContinue
+        }
+    }
+
+    Test "Test-BinaryMagic rejects an HTML error page" {
+        $tmp = [System.IO.Path]::GetTempFileName()
+        try {
+            [System.IO.File]::WriteAllText($tmp, "<html><body>404 Not Found</body></html>")
+            if (Test-BinaryMagic -Path $tmp) { throw "An HTML body was accepted as a binary" }
+        } finally {
+            Remove-Item $tmp -Force -ErrorAction SilentlyContinue
+        }
+    }
+
+    Test "Test-BinaryMagic rejects a missing file" {
+        if (Test-BinaryMagic -Path "/nonexistent/binary-xyz") { throw "A missing file was accepted" }
     }
 }
 

package/scripts/tests/install-browser4-cli.tests.sh

@@ -27,8 +27,8 @@ dim()    { echo -e "\033[2m$*\033[0m"; }
 
 test() {
     local name="$1"
-    local fn="$2"
-    if "$fn"; then
+    shift
+    if "$@"; then
         PASS=$((PASS + 1))
         green "  PASS  $name"
     else
@@ -109,26 +109,65 @@ test "--source invalid rejected" bash -c "
     bash '$INSTALL_SCRIPT' --source invalid --dry-run 2>&1 | grep -qi 'github.*oss\|must be'
 "
 
+test "--version rejects a following option as its value" bash -c "
+    rc=0
+    out=\$(bash '$INSTALL_SCRIPT' --version --dry-run 2>&1) || rc=\$?
+    [[ \$rc -ne 0 ]] && echo \"\$out\" | grep -q 'requires a value'
+"
+
+test "--install-dir rejects a following option as its value" bash -c "
+    rc=0
+    out=\$(bash '$INSTALL_SCRIPT' --install-dir --silent 2>&1) || rc=\$?
+    [[ \$rc -ne 0 ]] && echo \"\$out\" | grep -q 'requires a value'
+"
+
+test "--version accepts a bare semver and prefixes it with v" bash -c "
+    bash '$INSTALL_SCRIPT' --locate --version 4.13.18 2>&1 | grep -q 'releases/download/v4\.13\.18/'
+"
+
+test "--version with the v prefix is left untouched" bash -c "
+    bash '$INSTALL_SCRIPT' --locate --version v4.13.18 2>&1 | grep -q 'releases/download/v4\.13\.18/'
+"
+
 test "--dry-run flag accepted" bash -c "
-    bash '$INSTALL_SCRIPT' --dry-run 2>&1 | grep -qi 'DRY-RUN\|dry-run\|Install'
+    bash '$INSTALL_SCRIPT' --dry-run 2>&1 | grep -q 'DRY-RUN'
 "
 
-test "--silent flag accepted" bash -c "
-    bash '$INSTALL_SCRIPT' --silent --dry-run 2>&1 | grep -v '^$' | head -1 | grep -qv '→\|step'
+test "--silent suppresses progress output" bash -c "
+    out=\$(bash '$INSTALL_SCRIPT' --silent --dry-run 2>&1)
+    echo \"\$out\" | grep -q 'DRY-RUN' && ! echo \"\$out\" | grep -q 'Install:'
 "
 
 test "--skip-local flag accepted" bash -c "
-    bash '$INSTALL_SCRIPT' --skip-local --dry-run 2>&1 | grep -qi 'skip\|DRY-RUN\|Already\|Install'
+    bash '$INSTALL_SCRIPT' --skip-local --dry-run 2>&1 | grep -q 'Skipping local binary check'
 "
 
 test "--no-path flag accepted" bash -c "
-    bash '$INSTALL_SCRIPT' --no-path --dry-run 2>&1 | grep -vq 'Added to PATH'
+    ! bash '$INSTALL_SCRIPT' --no-path --dry-run 2>&1 | grep -q 'Added to PATH'
 "
 
 test "unknown arg rejected" bash -c "
     bash '$INSTALL_SCRIPT' --bogus-flag 2>&1 | grep -q 'Unknown argument'
 "
 
+# A PATH that has everything the diagnostics need except the download tooling.
+# `--locate` must still answer; a real install must refuse with a clear message
+# instead of failing later with 'curl: command not found'.
+minimal_path_locate_works() {
+    local dir; dir="$(mktemp -d)"
+    local bash_bin; bash_bin=$(command -v bash)
+    local tool tool_path
+    for tool in uname stat cat grep awk sed dirname basename tr od; do
+        tool_path=$(command -v "$tool") && ln -sf "$tool_path" "$dir/$tool"
+    done
+    local locate_rc=0 install_rc=0
+    PATH="$dir" "$bash_bin" "$INSTALL_SCRIPT" --locate >/dev/null 2>&1 || locate_rc=$?
+    PATH="$dir" "$bash_bin" "$INSTALL_SCRIPT" --dry-run --no-path >/dev/null 2>&1 || install_rc=$?
+    rm -rf "$dir"
+    [[ $locate_rc -eq 0 ]] && [[ $install_rc -ne 0 ]]
+}
+test "--locate needs no download tooling, installing does" minimal_path_locate_works
+
 echo ""
 
 # ── Locate mode ────────────────────────────────────────
@@ -191,6 +230,103 @@ test "OSS URL NOT using broken download/latest pattern" bash -c "
 
 echo ""
 
+# ── Download integrity (stubbed curl -- no network) ────
+
+echo "--- Download integrity ---" | cyan
+
+STUB_DIR="$(mktemp -d)"
+mkdir -p "$STUB_DIR"
+
+cat > "$STUB_DIR/curl" << 'STUBEOF'
+#!/usr/bin/env bash
+# curl stub for the installer tests.  Honours -o <file>, takes the body from
+# STUB_BODY (html = an error page, elf = a native binary), reports STUB_STATUS
+# and records its own command line in STUB_ARGS_FILE so a test can assert on
+# the headers the installer would have sent.
+out=""
+printf '%s\n' "$*" >> "${STUB_ARGS_FILE:-/dev/null}"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -o) out="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+if [[ "${STUB_STATUS:-200}" == "200" ]]; then
+  if [[ "${STUB_BODY:-elf}" == "html" ]]; then
+    { printf '<html>'; head -c 200000 /dev/zero | tr '\0' 'x'; printf '</html>'; } > "$out"
+  else
+    { printf '\177ELF\002\001\001\000'; head -c 200000 /dev/zero; } > "$out"
+  fi
+fi
+echo "${STUB_STATUS:-200}"
+exit "${STUB_EXIT:-0}"
+STUBEOF
+chmod +x "$STUB_DIR/curl"
+
+stub_install() {
+    # $1 = body kind (html|elf), $2 = source, $3 = args file, $4 = extra env
+    local body="$1" source="$2" args_file="$3" dir rc=0
+    dir="$(mktemp -d)"
+    STUB_BODY="$body" STUB_ARGS_FILE="$args_file" \
+        PATH="$STUB_DIR:$PATH" bash "$INSTALL_SCRIPT" \
+        --source "$source" --no-path --skip-backend --skip-local \
+        --install-dir "$dir/inst" >"$dir/out" 2>&1 || rc=$?
+    printf '%s\n' "$rc" > "$dir/rc"
+    echo "$dir"
+}
+
+download_rejects_html() {
+    local args; args="$(mktemp)"
+    local dir; dir=$(stub_install html oss "$args")
+    local rc; rc=$(cat "$dir/rc")
+    local rejected=0
+    grep -q 'not a native executable' "$dir/out" && rejected=1
+    rm -rf "$dir" "$args"
+    [[ "$rc" -ne 0 ]] && [[ $rejected -eq 1 ]]
+}
+
+download_accepts_elf() {
+    local args; args="$(mktemp)"
+    local dir; dir=$(stub_install elf oss "$args")
+    local rc; rc=$(cat "$dir/rc")
+    local installed; installed=$(find "$dir/inst" -maxdepth 1 -type f -name 'browser4-cli-*' 2>/dev/null | head -1)
+    local ok=1
+    [[ "$rc" -eq 0 ]] && [[ -n "$installed" ]] && [[ -x "$installed" ]] && ok=0
+    rm -rf "$dir" "$args"
+    [[ $ok -eq 0 ]]
+}
+
+token_not_sent_to_oss() {
+    local args; args="$(mktemp)"
+    export GITHUB_TOKEN=stub-secret-token
+    local dir; dir=$(stub_install elf oss "$args")
+    unset GITHUB_TOKEN
+    local leaked=0
+    grep -q 'stub-secret-token' "$args" && leaked=1
+    rm -rf "$dir" "$args"
+    [[ $leaked -eq 0 ]]
+}
+
+token_sent_to_github() {
+    local args; args="$(mktemp)"
+    export GITHUB_TOKEN=stub-secret-token
+    local dir; dir=$(stub_install elf github "$args")
+    unset GITHUB_TOKEN
+    local sent=0
+    grep -q 'stub-secret-token' "$args" && sent=1
+    rm -rf "$dir" "$args"
+    [[ $sent -eq 1 ]]
+}
+
+test "download rejects an HTML error page (bad magic bytes)" download_rejects_html
+test "download accepts a native binary body" download_accepts_elf
+test "GITHUB_TOKEN is never sent to the OSS mirror" token_not_sent_to_oss
+test "GITHUB_TOKEN is sent to GitHub" token_sent_to_github
+
+rm -rf "$STUB_DIR"
+
+echo ""
+
 # ── Functions (extracted via copy without main call) ──
 
 echo "--- Functions ---" | cyan
@@ -232,7 +368,9 @@ test "get_default_install_dir returns non-empty" bash -c "
 
 test "detect_china_locale returns 0 or 1 (no crash)" bash -c "
     source '$FUNC_TEST_SCRIPT' >/dev/null 2>&1
-    detect_china_locale && true || true
+    rc=0
+    detect_china_locale || rc=\$?
+    [[ \$rc -eq 0 || \$rc -eq 1 ]]
 "
 
 test "detect_os returns valid OS" bash -c "
@@ -323,7 +461,10 @@ test "header is ASCII (no box-drawing chars)" bash -c "
 "
 
 test "header does not contain Unicode box-drawing" bash -c "
-    ! bash '$INSTALL_SCRIPT' --locate 2>&1 | grep -P '[\x{2500}-\x{257F}]' 2>/dev/null || true
+    # Portable (no grep -P): drop the ANSI colour escapes first, then any byte
+    # outside printable ASCII would be a non-ASCII character; the installer
+    # prints ASCII only.
+    ! bash '$INSTALL_SCRIPT' --locate 2>&1 | tr -d '\033' | LC_ALL=C grep -q '[^ -~]'
 "
 
 echo ""
@@ -333,7 +474,13 @@ echo ""
 echo "--- Edge cases ---" | cyan
 
 test "double dash in --version handled (no operator parsing)" bash -c "
-    bash '$INSTALL_SCRIPT' --locate 2>&1 | grep -q 'version'
+    # '--version --dry-run' must not be read as the tag '--dry-run'; the value
+    # has to be a release tag, and a bare semver gets the 'v' prefix.
+    rc=0
+    out=\$(bash '$INSTALL_SCRIPT' --version --dry-run 2>&1) || rc=\$?
+    [[ \$rc -ne 0 ]] || exit 1
+    echo \"\$out\" | grep -q 'looks like another option' || exit 1
+    bash '$INSTALL_SCRIPT' --locate --version 4.13.18 2>&1 | grep -q 'releases/download/v4\.13\.18/'
 "
 
 test "empty --version with dry-run doesn't download" bash -c "