Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(agent-install): paged version discovery, checksum verify, busybox support (A1-A3)

Juan Denis11066bb130a6
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 22611e9f..f0e28d6d 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -1835,6 +1835,19 @@ def get_install_script_linux():
content = content.replace('https://your-serverkit.com', server_url)
content = content.replace('jhd3197/ServerKit', GITHUB_REPO)
+ # Inject the agent version the panel already resolved so enrollment does
+ # not depend on the installer rediscovering it via the GitHub API. Best
+ # effort: on failure the placeholder stays empty and the script falls
+ # back to its own GitHub discovery.
+ release = _get_latest_agent_release()
+ version = (release or {}).get('version') or ''
+ if version and all(c.isalnum() or c in '._-' for c in version):
+ content = content.replace(
+ 'SERVERKIT_AGENT_VERSION=""',
+ f'SERVERKIT_AGENT_VERSION="{version}"',
+ 1
+ )
+
return Response(
content,
mimetype='text/x-shellscript',
@@ -1956,10 +1969,13 @@ def _get_latest_agent_release():
return _releases_cache['data']
try:
- # Fetch releases from GitHub
+ # Fetch releases from GitHub. per_page=100: agent-v* tags share this
+ # repo with panel releases, which can push them off the default
+ # 30-entry first page.
response = requests.get(
f'https://api.github.com/repos/{GITHUB_REPO}/releases',
headers={'Accept': 'application/vnd.github.v3+json'},
+ params={'per_page': 100},
timeout=10
)
response.raise_for_status()
diff --git a/scripts/install.sh b/scripts/install.sh
index 4ce347d5..c715e254 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -44,6 +44,11 @@ SERVER_URL=""
SERVER_NAME=""
VERSION="latest"
+# Version injected by the panel when it serves this script (the panel already
+# resolves the latest agent release for its update endpoints). Empty means
+# discover the version via the GitHub API in get_latest_version().
+SERVERKIT_AGENT_VERSION=""
+
print_banner() {
echo
printf " ${V1}${BOLD}╔═╗┌─┐┌─┐┌┬┐┌─┐┬┌─┐${NC}\n"
@@ -92,18 +97,22 @@ parse_args() {
while [[ $# -gt 0 ]]; do
case $1 in
--token|-t)
+ [[ $# -ge 2 ]] || log_error "Option $1 requires a value"
TOKEN="$2"
shift 2
;;
--server|-s)
+ [[ $# -ge 2 ]] || log_error "Option $1 requires a value"
SERVER_URL="$2"
shift 2
;;
--name|-n)
+ [[ $# -ge 2 ]] || log_error "Option $1 requires a value"
SERVER_NAME="$2"
shift 2
;;
--version|-v)
+ [[ $# -ge 2 ]] || log_error "Option $1 requires a value"
VERSION="$2"
shift 2
;;
@@ -172,30 +181,84 @@ check_dependencies() {
}
get_latest_version() {
- if [[ "$VERSION" == "latest" ]]; then
- log_info "Fetching latest version..."
- VERSION=$(curl -fsSL "https://api.github.com/repos/${GITHUB_REPO}/releases" | \
- grep -oP '"tag_name": "agent-v\K[^"]+' | head -1)
+ if [[ "$VERSION" != "latest" ]]; then
+ return 0
+ fi
- if [[ -z "$VERSION" ]]; then
- log_error "Failed to fetch latest version"
- fi
- log_info "Latest version: v${VERSION}"
+ # The panel injects the version it already resolved when serving this
+ # script — use it and keep GitHub out of the enrollment path entirely.
+ if [[ -n "$SERVERKIT_AGENT_VERSION" ]]; then
+ VERSION="$SERVERKIT_AGENT_VERSION"
+ log_info "Using panel-resolved version: v${VERSION}"
+ return 0
+ fi
+
+ log_info "Fetching latest version..."
+
+ # Agent tags share this repo with panel releases, which can push every
+ # agent-v* tag off the first page — so page through instead of trusting
+ # the default (30-entry) first page. Capped at 3 pages of 100.
+ local page releases
+ VERSION=""
+ for page in 1 2 3; do
+ releases=$(curl -fsSL "https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=100&page=${page}") || break
+ VERSION=$(printf '%s\n' "$releases" | grep -o '"tag_name": *"agent-v[^"]*"' | head -1 | sed -e 's/.*agent-v//' -e 's/"$//') || true
+ [[ -n "$VERSION" ]] && break
+ # A page with no tags at all means the release list is exhausted.
+ printf '%s' "$releases" | grep -q '"tag_name"' || break
+ done
+
+ if [[ -z "$VERSION" ]]; then
+ log_error "Failed to fetch latest version"
fi
+ log_info "Latest version: v${VERSION}"
+}
+
+# Verify the downloaded archive against the release's checksums.txt.
+# Best-effort when checksums.txt is unavailable (older releases); a present-
+# but-mismatching checksum is a hard failure.
+verify_checksum() {
+ local tmp_dir="$1" asset_name="$2"
+ local checksums_url="https://github.com/${GITHUB_REPO}/releases/download/agent-v${VERSION}/checksums.txt"
+
+ if ! command -v sha256sum &> /dev/null; then
+ log_warn "sha256sum not available — skipping checksum verification"
+ return 0
+ fi
+
+ if ! curl -fsSL "$checksums_url" -o "${tmp_dir}/checksums.txt"; then
+ log_warn "Could not download checksums.txt — skipping verification"
+ return 0
+ fi
+
+ if ! grep -q "$asset_name" "${tmp_dir}/checksums.txt"; then
+ log_warn "checksums.txt has no entry for ${asset_name} — skipping verification"
+ return 0
+ fi
+
+ if ! (cd "$tmp_dir" && sha256sum -c <(grep "$asset_name" checksums.txt) >/dev/null 2>&1); then
+ rm -rf "$tmp_dir"
+ log_error "Checksum verification FAILED for ${asset_name} — aborting install"
+ fi
+
+ log_success "Checksum verified"
}
download_agent() {
log_info "Downloading ServerKit Agent v${VERSION}..."
- DOWNLOAD_URL="https://github.com/${GITHUB_REPO}/releases/download/agent-v${VERSION}/serverkit-agent-${VERSION}-linux-${ARCH}.tar.gz"
+ ASSET_NAME="serverkit-agent-${VERSION}-linux-${ARCH}.tar.gz"
+ DOWNLOAD_URL="https://github.com/${GITHUB_REPO}/releases/download/agent-v${VERSION}/${ASSET_NAME}"
TMP_DIR=$(mktemp -d)
- ARCHIVE="${TMP_DIR}/serverkit-agent.tar.gz"
+ ARCHIVE="${TMP_DIR}/${ASSET_NAME}"
if ! curl -fsSL "$DOWNLOAD_URL" -o "$ARCHIVE"; then
rm -rf "$TMP_DIR"
log_error "Failed to download agent from: $DOWNLOAD_URL"
fi
+ verify_checksum "$TMP_DIR" "$ASSET_NAME"
+
# Extract binary
log_info "Extracting agent..."
tar -xzf "$ARCHIVE" -C "$TMP_DIR"
@@ -215,12 +278,24 @@ create_user() {
log_info "User $SERVICE_USER already exists"
else
log_info "Creating service user: $SERVICE_USER"
- useradd -r -s /bin/false -d /nonexistent "$SERVICE_USER"
+ if command -v useradd &> /dev/null; then
+ useradd -r -s /bin/false -d /nonexistent "$SERVICE_USER"
+ elif command -v adduser &> /dev/null; then
+ # Alpine/busybox ships adduser instead of useradd
+ adduser -S -D -H -s /bin/false "$SERVICE_USER"
+ else
+ log_error "Cannot create user: neither useradd nor adduser found"
+ fi
fi
# Add to docker group if it exists
if getent group docker > /dev/null 2>&1; then
- usermod -aG docker "$SERVICE_USER"
+ if command -v usermod &> /dev/null; then
+ usermod -aG docker "$SERVICE_USER"
+ else
+ # busybox equivalent of usermod -aG
+ addgroup "$SERVICE_USER" docker
+ fi
log_info "Added $SERVICE_USER to docker group"
fi
}
@@ -373,4 +448,12 @@ main() {
print_success
}
+# Sourcing this file (e.g. from scripts/test/test_agent_install.sh) defines
+# every function above for unit testing without running an install. Piped
+# execution (curl | bash) has no BASH_SOURCE[0], so only a real `source`
+# takes the early return.
+if [ -n "${BASH_SOURCE[0]:-}" ] && [ "${BASH_SOURCE[0]}" != "$0" ]; then
+ return 0
+fi
+
main "$@"
diff --git a/scripts/test-routing.sh b/scripts/test-routing.sh
index a9209cb4..c6e57181 100644
--- a/scripts/test-routing.sh
+++ b/scripts/test-routing.sh
@@ -47,26 +47,36 @@ echo ""
PASS=0
FAIL=0
+# NOTE: every probe below must be run inside an `if`/`||` so a failing check
+# is *recorded* instead of killing the script via `set -e`. `((PASS++))` is
+# also a set -e trap (arithmetic returns the pre-increment value, so the first
+# increment from 0 "fails") — use the assignment form instead.
check() {
local name=$1
local result=$2
if [ "$result" = "0" ]; then
echo -e " ${GREEN}✓${NC} $name"
- ((PASS++))
+ PASS=$((PASS + 1))
else
echo -e " ${RED}✗${NC} $name"
- ((FAIL++))
+ FAIL=$((FAIL + 1))
fi
}
# Test 1: Port accessibility
echo "1. Checking port accessibility..."
if command -v nc &> /dev/null; then
- nc -z -w 2 127.0.0.1 $PORT 2>/dev/null
- check "Port $PORT is accessible on localhost" $?
+ if nc -z -w 2 127.0.0.1 "$PORT" 2>/dev/null; then
+ check "Port $PORT is accessible on localhost" 0
+ else
+ check "Port $PORT is accessible on localhost" 1
+ fi
elif command -v curl &> /dev/null; then
- curl -s --connect-timeout 2 http://127.0.0.1:$PORT/ > /dev/null 2>&1
- check "Port $PORT is accessible on localhost" $?
+ if curl -s --connect-timeout 2 "http://127.0.0.1:$PORT/" > /dev/null 2>&1; then
+ check "Port $PORT is accessible on localhost" 0
+ else
+ check "Port $PORT is accessible on localhost" 1
+ fi
else
echo -e " ${YELLOW}!${NC} Cannot check port (nc and curl not available)"
fi
@@ -96,8 +106,14 @@ fi
echo ""
echo "3. Testing Nginx configuration syntax..."
if command -v nginx &> /dev/null; then
- sudo nginx -t 2>&1 | grep -q "successful"
- check "Nginx config syntax is valid" $?
+ # nginx -t needs root; only reach for sudo when we aren't root already
+ SUDO=""
+ [ "$(id -u)" -ne 0 ] && SUDO="sudo"
+ if $SUDO nginx -t 2>&1 | grep -q "successful"; then
+ check "Nginx config syntax is valid" 0
+ else
+ check "Nginx config syntax is valid" 1
+ fi
else
echo -e " ${YELLOW}!${NC} Nginx command not available"
fi
@@ -106,18 +122,26 @@ fi
echo ""
echo "4. Checking Nginx service status..."
if command -v systemctl &> /dev/null; then
- systemctl is-active nginx > /dev/null 2>&1
- check "Nginx service is running" $?
+ if systemctl is-active nginx > /dev/null 2>&1; then
+ check "Nginx service is running" 0
+ else
+ check "Nginx service is running" 1
+ fi
else
- ps aux | grep -v grep | grep -q nginx
- check "Nginx process is running" $?
+ if ps aux | grep -v grep | grep -q nginx; then
+ check "Nginx process is running" 0
+ else
+ check "Nginx process is running" 1
+ fi
fi
# Test 5: Direct backend request
echo ""
echo "5. Testing direct backend request..."
if command -v curl &> /dev/null; then
- HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 http://127.0.0.1:$PORT/ 2>/dev/null || echo "000")
+ # NB: on connection failure curl still prints "000" via -w AND exits
+ # non-zero — `|| echo 000` would concatenate to "000000" and false-pass.
+ HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 "http://127.0.0.1:$PORT/" 2>/dev/null) || HTTP_CODE="000"
if [ "$HTTP_CODE" != "000" ]; then
check "Backend responds (HTTP $HTTP_CODE)" 0
else
@@ -134,7 +158,7 @@ if [ -n "$DOMAIN" ]; then
echo "6. Testing domain routing..."
if command -v curl &> /dev/null; then
# Test via Host header to localhost (simulates domain routing)
- HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 -H "Host: $DOMAIN" http://127.0.0.1/ 2>/dev/null || echo "000")
+ HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 -H "Host: $DOMAIN" http://127.0.0.1/ 2>/dev/null) || HTTP_CODE="000"
if [ "$HTTP_CODE" != "000" ] && [ "$HTTP_CODE" != "404" ]; then
check "Domain routing works (HTTP $HTTP_CODE)" 0
else
@@ -165,7 +189,7 @@ if command -v docker &> /dev/null; then
PORT_BINDINGS=$(docker port "$APP_NAME" 2>/dev/null || echo "")
if [ -n "$PORT_BINDINGS" ]; then
echo -e " Port bindings:"
- echo "$PORT_BINDINGS" | while read line; do
+ echo "$PORT_BINDINGS" | while read -r line; do
echo -e " $line"
done
fi
@@ -182,7 +206,7 @@ echo -e " ${GREEN}Passed:${NC} $PASS"
echo -e " ${RED}Failed:${NC} $FAIL"
echo ""
-if [ $FAIL -eq 0 ]; then
+if [ "$FAIL" -eq 0 ]; then
echo -e "${GREEN}All checks passed! Routing should be working.${NC}"
exit 0
else
diff --git a/scripts/test/test_agent_install.sh b/scripts/test/test_agent_install.sh
new file mode 100644
index 00000000..50840531
--- /dev/null
+++ b/scripts/test/test_agent_install.sh
@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+#
+# Unit tests for scripts/install.sh — the AGENT installer that the panel
+# serves at GET /api/v1/servers/install.sh (NOT the repo-root panel
+# install.sh).
+#
+# install.sh is source-able: when sourced it defines every function and then
+# returns *before* main() (the BASH_SOURCE guard). Combined with a curl stub
+# on PATH that serves GitHub-API fixtures, that lets us exercise version
+# discovery (paging!), checksum verification and argument parsing with no
+# network and no root.
+#
+# Run: bash scripts/test/test_agent_install.sh
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INSTALL_SH="$SCRIPT_DIR/../install.sh"
+
+PASS=0
+FAIL=0
+SKIP=0
+ok() { PASS=$((PASS + 1)); printf ' \033[32m✔\033[0m %s\n' "$1"; }
+bad() { FAIL=$((FAIL + 1)); printf ' \033[31m✘\033[0m %s\n' "$1"; }
+skip() { SKIP=$((SKIP + 1)); printf ' \033[33m∼\033[0m %s (skipped)\n' "$1"; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# --------------------------------------------------------------------------
+# curl stub: serves GitHub-API release pages / release assets from fixture
+# files in $FIXTURES, records every requested URL in $CURL_LOG, and mimics
+# `curl -f` on a missing fixture (exit 22).
+# --------------------------------------------------------------------------
+STUB_BIN="$WORK/bin"
+FIXTURES="$WORK/fixtures"
+CURL_LOG="$WORK/curl.log"
+mkdir -p "$STUB_BIN" "$FIXTURES"
+: > "$CURL_LOG"
+
+cat > "$STUB_BIN/curl" <<'EOF'
+#!/bin/bash
+url=""; out=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -o) out="$2"; shift 2 ;;
+ -*) shift ;;
+ *) url="$1"; shift ;;
+ esac
+done
+printf '%s\n' "$url" >> "$CURL_LOG"
+case "$url" in
+ *"/releases?"*) body="$FIXTURES/releases_page_${url##*page=}.json" ;;
+ *"/checksums.txt") body="$FIXTURES/checksums.txt" ;;
+ *) body="$FIXTURES/asset" ;;
+esac
+[ -f "$body" ] || exit 22
+if [ -n "$out" ]; then cp "$body" "$out"; else cat "$body"; fi
+EOF
+chmod +x "$STUB_BIN/curl"
+export PATH="$STUB_BIN:$PATH"
+export FIXTURES CURL_LOG
+
+# --------------------------------------------------------------------------
+# Source install.sh (functions only — the BASH_SOURCE guard skips main).
+# --------------------------------------------------------------------------
+# shellcheck disable=SC1090
+source "$INSTALL_SH"
+set +e +u # hand control back to the harness; tests re-arm set -e per subshell
+
+printf '\nagent install.sh unit tests\n\n'
+
+# --------------------------------------------------------------------------
+# T1 — paged version discovery. The repo is shared with panel releases, so a
+# first page full of v1.7.x tags must NOT break enrollment: discovery has to
+# request per_page=100 and keep paging until it finds an agent-v* tag.
+# --------------------------------------------------------------------------
+{
+ printf '['
+ for i in $(seq 1 30); do printf '{"tag_name": "v1.7.%s"},' "$i"; done
+ printf '{"tag_name": "v1.7.99"}]'
+} > "$FIXTURES/releases_page_1.json"
+printf '[{"tag_name": "v1.6.0"},{"tag_name": "agent-v0.3.2"},{"tag_name": "agent-v0.3.1"}]' \
+ > "$FIXTURES/releases_page_2.json"
+
+: > "$CURL_LOG"
+got="$(
+ set -Eeuo pipefail
+ VERSION="latest"; SERVERKIT_AGENT_VERSION=""; GITHUB_REPO="jhd3197/ServerKit"
+ get_latest_version >/dev/null
+ printf '%s' "$VERSION"
+)"
+if [ "$got" = "0.3.2" ]; then
+ ok "paged discovery finds agent-v0.3.2 on page 2 behind a page of panel tags"
+else
+ bad "paged discovery: VERSION=[$got], want 0.3.2"
+fi
+if grep -q 'per_page=100' "$CURL_LOG"; then
+ ok "release requests ask GitHub for per_page=100"
+else
+ bad "per_page=100 missing from release requests"
+fi
+if grep -q 'page=2' "$CURL_LOG" && ! grep -q 'page=3' "$CURL_LOG"; then
+ ok "discovery pages forward and stops once a tag is found (no page=3 request)"
+else
+ bad "unexpected page sequence: $(tr '\n' ' ' < "$CURL_LOG")"
+fi
+
+# --------------------------------------------------------------------------
+# T2 — discovery must fail LOUDLY (exit 1), not silently, when no agent-v*
+# tag exists on any page; and an empty page ends the paging early.
+# --------------------------------------------------------------------------
+mkdir -p "$WORK/fx2"
+printf '[{"tag_name": "v1.7.0"}]' > "$WORK/fx2/releases_page_1.json"
+printf '[]' > "$WORK/fx2/releases_page_2.json"
+: > "$CURL_LOG"
+if (
+ set -Eeuo pipefail
+ FIXTURES="$WORK/fx2"
+ VERSION="latest"; SERVERKIT_AGENT_VERSION=""; GITHUB_REPO="jhd3197/ServerKit"
+ get_latest_version
+) >/dev/null 2>&1; then
+ bad "discovery must exit non-zero when no agent-v tag exists"
+else
+ ok "discovery fails loudly (exit 1) when no agent-v tag exists on any page"
+fi
+if grep -q 'page=2' "$CURL_LOG" && ! grep -q 'page=3' "$CURL_LOG"; then
+ ok "an empty release page stops the paging (no page=3 request)"
+else
+ bad "empty-page stop broken: $(tr '\n' ' ' < "$CURL_LOG")"
+fi
+
+# --------------------------------------------------------------------------
+# T3 — the panel-injected version short-circuits GitHub discovery entirely,
+# and an explicit --version is left untouched.
+# --------------------------------------------------------------------------
+: > "$CURL_LOG"
+got="$(
+ set -Eeuo pipefail
+ VERSION="latest"; SERVERKIT_AGENT_VERSION="9.9.9"; GITHUB_REPO="jhd3197/ServerKit"
+ get_latest_version >/dev/null
+ printf '%s' "$VERSION"
+)"
+if [ "$got" = "9.9.9" ] && [ ! -s "$CURL_LOG" ]; then
+ ok "panel-injected SERVERKIT_AGENT_VERSION is used without any GitHub call"
+else
+ bad "panel-injected version: VERSION=[$got], curl calls: $(tr '\n' ' ' < "$CURL_LOG")"
+fi
+
+: > "$CURL_LOG"
+got="$(
+ set -Eeuo pipefail
+ VERSION="1.2.3"; SERVERKIT_AGENT_VERSION=""; GITHUB_REPO="jhd3197/ServerKit"
+ get_latest_version >/dev/null
+ printf '%s' "$VERSION"
+)"
+if [ "$got" = "1.2.3" ] && [ ! -s "$CURL_LOG" ]; then
+ ok "an explicit --version skips discovery"
+else
+ bad "explicit version: VERSION=[$got]"
+fi
+
+# --------------------------------------------------------------------------
+# T4 — checksum verification: pass on match, HALT on mismatch, warn-and-
+# continue when checksums.txt is not published (older releases).
+# --------------------------------------------------------------------------
+if command -v sha256sum >/dev/null 2>&1; then
+ asset="serverkit-agent-0.3.2-linux-amd64.tar.gz"
+
+ t="$WORK/ck-good"; mkdir -p "$t"
+ printf 'agent-bytes' > "$t/$asset"
+ sha="$(sha256sum "$t/$asset" | cut -d' ' -f1)"
+ printf '%s %s\n' "$sha" "$asset" > "$FIXTURES/checksums.txt"
+ if (
+ set -Eeuo pipefail
+ VERSION="0.3.2"; GITHUB_REPO="jhd3197/ServerKit"
+ verify_checksum "$t" "$asset"
+ ) >/dev/null 2>&1; then
+ ok "verify_checksum passes on a matching sha256"
+ else
+ bad "verify_checksum rejected a good archive"
+ fi
+
+ t="$WORK/ck-bad"; mkdir -p "$t"
+ printf 'agent-bytes' > "$t/$asset"
+ printf '%s %s\n' \
+ "0000000000000000000000000000000000000000000000000000000000000000" \
+ "$asset" > "$FIXTURES/checksums.txt"
+ if (
+ set -Eeuo pipefail
+ VERSION="0.3.2"; GITHUB_REPO="jhd3197/ServerKit"
+ verify_checksum "$t" "$asset"
+ ) >/dev/null 2>&1; then
+ bad "verify_checksum must HALT on a checksum mismatch"
+ else
+ ok "verify_checksum halts (exit 1) on a checksum mismatch"
+ fi
+
+ t="$WORK/ck-missing"; mkdir -p "$t"
+ printf 'agent-bytes' > "$t/$asset"
+ rm -f "$FIXTURES/checksums.txt"
+ if (
+ set -Eeuo pipefail
+ VERSION="0.3.2"; GITHUB_REPO="jhd3197/ServerKit"
+ verify_checksum "$t" "$asset"
+ ) >/dev/null 2>&1; then
+ ok "missing checksums.txt is best-effort (warn + continue)"
+ else
+ bad "missing checksums.txt must not abort the install"
+ fi
+
+ t="$WORK/ck-noentry"; mkdir -p "$t"
+ printf 'agent-bytes' > "$t/$asset"
+ printf '%s some-other-file.tar.gz\n' "$sha" > "$FIXTURES/checksums.txt"
+ if (
+ set -Eeuo pipefail
+ VERSION="0.3.2"; GITHUB_REPO="jhd3197/ServerKit"
+ verify_checksum "$t" "$asset"
+ ) >/dev/null 2>&1; then
+ ok "checksums.txt without our asset entry is best-effort (warn + continue)"
+ else
+ bad "a checksums.txt missing our entry must not abort the install"
+ fi
+ rm -f "$FIXTURES/checksums.txt"
+else
+ skip "checksum verification — sha256sum unavailable on this host"
+fi
+
+# --------------------------------------------------------------------------
+# T5 — argument parsing: an option with a missing value must die loudly
+# (previously `shift 2` failed silently under set -e), and required-arg
+# validation still works.
+# --------------------------------------------------------------------------
+out="$(bash "$INSTALL_SH" --token 2>&1)"; rc=$?
+if [ "$rc" -ne 0 ] && printf '%s' "$out" | grep -q "requires a value"; then
+ ok "--token with no value fails loudly with 'requires a value'"
+else
+ bad "--token with no value: rc=$rc out=[$out]"
+fi
+
+out="$(bash "$INSTALL_SH" --token abc 2>&1)"; rc=$?
+if [ "$rc" -ne 0 ] && printf '%s' "$out" | grep -q "Server URL is required"; then
+ ok "missing --server is still reported after the arg-guard change"
+else
+ bad "missing --server: rc=$rc out=[$out]"
+fi
+
+out="$(bash "$INSTALL_SH" --help 2>&1)"; rc=$?
+if [ "$rc" -eq 0 ] && printf '%s' "$out" | grep -q "Usage"; then
+ ok "--help still exits 0 with usage"
+else
+ bad "--help: rc=$rc"
+fi
+
+# --------------------------------------------------------------------------
+# T6 — the source guard must not break piped execution (curl | bash), where
+# BASH_SOURCE[0] is unset. No args → main runs → 'token is required'.
+# --------------------------------------------------------------------------
+out="$(bash < "$INSTALL_SH" 2>&1)"; rc=$?
+if [ "$rc" -ne 0 ] && printf '%s' "$out" | grep -q "Registration token is required"; then
+ ok "piped execution (stdin, as curl|bash) still reaches main()"
+else
+ bad "piped execution broken by the source guard: rc=$rc out=[$out]"
+fi
+
+# --------------------------------------------------------------------------
+# T7 — create_user falls back to busybox adduser -S -D -H when useradd is
+# absent (Alpine). Restricted PATH: only these stubs are visible.
+# --------------------------------------------------------------------------
+UBIN="$WORK/ubin"; mkdir -p "$UBIN"
+printf '#!/bin/bash\nexit 1\n' > "$UBIN/id" # user does not exist yet
+printf '#!/bin/bash\nexit 2\n' > "$UBIN/getent" # no docker group
+cat > "$UBIN/adduser" <<EOF
+#!/bin/bash
+printf '%s\n' "\$*" > "$WORK/adduser.args"
+EOF
+chmod +x "$UBIN"/*
+rm -f "$WORK/adduser.args"
+if (
+ set -Eeuo pipefail
+ PATH="$UBIN"
+ create_user
+) >/dev/null 2>&1 && grep -q -- '-S -D -H' "$WORK/adduser.args" 2>/dev/null; then
+ ok "create_user falls back to adduser -S -D -H when useradd is missing"
+else
+ bad "busybox adduser fallback broken: args=[$(cat "$WORK/adduser.args" 2>/dev/null)]"
+fi
+
+UBIN2="$WORK/ubin2"; mkdir -p "$UBIN2"
+printf '#!/bin/bash\nexit 1\n' > "$UBIN2/id"
+printf '#!/bin/bash\nexit 2\n' > "$UBIN2/getent"
+cat > "$UBIN2/useradd" <<EOF
+#!/bin/bash
+printf '%s\n' "\$*" > "$WORK/useradd.args"
+EOF
+chmod +x "$UBIN2"/*
+rm -f "$WORK/useradd.args"
+if (
+ set -Eeuo pipefail
+ PATH="$UBIN2"
+ create_user
+) >/dev/null 2>&1 && grep -q -- '-r' "$WORK/useradd.args" 2>/dev/null; then
+ ok "create_user still prefers useradd -r when it exists"
+else
+ bad "useradd path broken: args=[$(cat "$WORK/useradd.args" 2>/dev/null)]"
+fi
+
+# --------------------------------------------------------------------------
+# T8 — portability regression guard: no GNU-only grep -P may creep back in
+# (BusyBox/BSD grep lack it; it's what made discovery Alpine-hostile).
+# --------------------------------------------------------------------------
+if grep -Eq 'grep +-[a-zA-Z]*P' "$INSTALL_SH"; then
+ bad "install.sh reintroduced GNU-only 'grep -P'"
+else
+ ok "no GNU-only 'grep -P' in install.sh"
+fi
+
+# --------------------------------------------------------------------------
+printf '\n%d passed, %d failed, %d skipped\n\n' "$PASS" "$FAIL" "$SKIP"
+[ "$FAIL" -eq 0 ]