fix(installer): make the curl TLS floor structural, not per-call-site (backend#1252)

[LukasWodka]

Summary

The installer's TLS floor was opt-in per call site: CURL_SECURE was a bare constant that every curl invocation had to splice in by hand, and seven live invocations had silently lost it — including the POST in verify_credentials() that carries the client's password. This replaces the constant with a curl_secure() wrapper in scripts/lib/common.sh and routes every fetch in scripts/lib/*.sh through it, so the floor is structural rather than remembered.

Practical exploitability is low (modern curl/OpenSSL won't negotiate TLS 1.0/1.1 by default), but this installer targets customer-managed hosts, older distros, and TLS-inspecting corporate proxies that negotiate down to whatever the client permits — which is exactly why the repo adopted an explicit floor instead of trusting defaults. This was a deviation from our own stated control, on a path that carries a credential.

Related

Fixes tracebloc/backend#1252
Found in #399
Enforcement depends on tracebloc/.github#65 (see below)

Type of change

• Feature
• Bug fix
• Tech-debt / refactor
• Docs
• Security / hardening
• Breaking change

The wrapper

curl_secure() {
local _arg _stall_bounded=0
for_argin"$@";docase"$_arg"in --speed-limit|--speed-time) _stall_bounded=1;break ;; esacdonelocal -a _bounds=(--connect-timeout "${TB_CURL_CONNECT_TIMEOUT:-30}")
(( _stall_bounded ))|| _bounds+=(--max-time "${TB_CURL_MAX_TIME:-300}")
curl --tlsv1.2 "${_bounds[@]}""$@"
}

Four decisions worth reviewing:

Defaults are injected before"$@". curl honours the last occurrence of a repeated option, so a call site that wants a tighter bound still wins (-m 15 on the HEAD probe, -m 60 on the credential POST, --max-time 120 on the CLI download). No existing site loses its own tuning.

A stall-bounded transfer gets no --max-time.download_with_progress() and the k3d/kubectl binary fetches deliberately bound themselves with --speed-limit/--speed-time instead of a deadline, because a hard cap fails a slow-but-healthy link on a large download (the Docker Desktop DMG; and see the existing comment at _fetch_k3d_release). The wrapper detects those flags and adds a floor without ever adding a ceiling — so no already-correct call site changes its effective behaviour. Nine previously unbounded ones gain a deadline.

Plain curl, not command curl. The bats suite mocks transfers by defining a curl shell function; command would bypass every mock and dial the real network. Pinned by a test.

CURL_SECURE stays defined, unchanged, for any out-of-tree caller — but nothing in the repo reads it now. The wrapper names --tlsv1.2 itself, so growing the constant can never silently reshape every fetch in the installer. It also must stay a single flag: two call sites had quoted it ("$CURL_SECURE"), where a space-separated value collapses into one argv element that curl rejects. Both are now gone.

Converted: 18 call sites in scripts/lib/*.sh

Seven were the defect; eleven were already correct and were converted anyway, to leave one idiom (so copying a neighbouring line is always right) and to remove the two quoted-constant traps.

File	Was	Now
install-client-helm.sh:269	no floor — credential POST	wrapper, keeps -m 60
common.sh:326, :347	no floor	wrapper (HEAD probe keeps -m 15; download keeps stall detection)
gpu-amd.sh:29, :52	no floor, no timeout, no retry	wrapper + --max-time 30 on the scrape; .deb download now retry 3 5
gpu-nvidia.sh:92, :99	no floor, no timeout	wrapper + --max-time 30
gpu-nvidia.sh:80	floor, no timeout	wrapper + --max-time 30
gpu-plugins.sh:26	quoted constant, no timeout	wrapper
install-cli.sh:237	quoted constant	wrapper, keeps --max-time 120
preflight.sh:61	constant	wrapper, keeps --max-time 8
setup-linux.sh:320, :322	constant, no bound at all	wrapper + stall bounds (see Bugbot round below)
setup-linux.sh ×4	constant, no timeout	wrapper
setup-linux.sh:363, :365, :409	constant + own bounds	wrapper, bounds untouched
setup-macos.sh:11, :180	constant, no timeout	wrapper

Neither gpu-amd.sh:29 nor gpu-nvidia.sh:92/99 can be retry-wrapped: retry() reports its attempts on stdout, which in those three cases is the value being captured or the file content being written. Noted in comments at both sites.

scripts/install.sh keeps its seven hardcoded literals — it is the trust root that fetchescommon.sh, so it cannot source the wrapper. Unchanged, as intended.

Not on the ticket: the same defect on the Windows path

scripts/install-k8s.ps1:568,570 runs a bash here-string inside WSL2 containing the same two nvidia-container-toolkit fetches, also with no TLS floor and no timeout. It can't source common.sh, so the flags are spelled out inline the way the bootstrap spells them out. That makes nine fixed sites, not seven.

Enforcement — interim, and deliberately so

scripts/check-style.sh gains a third check that fails on a bare curl. It is explicitly marked interim in the code, with the retirement condition named: tracebloc/.github#65 already implements these rules properly (curl-tls + curl-timeout, via a quote-aware, heredoc-aware lexer rather than a grep) in a shared reusable workflow, and reports 20 findings against this repo today. That workflow is not on main yet, so no repo can reference it — and it ships soft-fail: true by default, so even once adopted it starts non-blocking. Waiting would leave the ticket's acceptance criterion unmet for an unknown number of weeks, so this repo gets a blocking grep now and deletes it when the shared caller lands.

The grep is narrow: \bcurl\b matches the bare command word and not curl_secure / curl_pid / nocurl, and it exempts lines naming --tlsv1.2 (the two trust-root files), comments, has curl / command -v curl presence tests, and the curl … | sh one-liner we print for users to copy. One user-facing copy line in preflight.sh carries the existing # style-guard: allow opt-out. The timeout half of the rule needs no grep — curl_secure supplies bounds to everything that can source it.

Verified both ways: clean on this branch, and exits 1 with the offending file:line when a bare curl is planted in a lib.

Bugbot round 1 — one real regression, fixed

_fetch_kubectl had no time bound of its own, so routing it through the wrapper handed it the default --max-time 300. kubectl is a ~50 MB binary, and this repo already documents (at _fetch_k3d_release, same file) that a fixed ceiling fails a slow-but-healthy link at that size — the wrapper would have made every retry fail where the fetch previously completed. Caught by a learned rule; a fair catch that the "no already-correct site changes behaviour" claim above missed, because this site was not already correct.

Fixed by giving both kubectl fetches the same --connect-timeout 15 --speed-limit 1024 --speed-time 60 as the k3d pair — which is also how curl_secure knows to skip its default deadline. Net result is strictly better than develop: the fetch was previously unbounded in both directions, so a mid-stream stall hung the step indefinitely.

Then audited the remaining seven sites that inherit the 300s default — get.docker.com, get-helm-3, the Homebrew script, stable.txt, the DMG checksum, the GPU device-plugin manifest, and the amdgpu-install package. All small text/script payloads. The only large downloads in the repo are kubectl, k3d and the Docker Desktop DMG; the latter two were already stall-bounded. Added a bats test pinning the kubectl bound, since nothing covered _fetch_kubectl before.

Test plan

Local, macOS (bash 3.2 + bash 5, shellcheck 0.11.0, bats 1.13.0):

• bats scripts/tests/*.bats — 421/424, up from 413/416 (8 new tests, same 3 pre-existing failures)
• The 3 failures are pre-existing on develop and environmental — validate_config tmpdir shape, the un-stamped DEFAULT_REF placeholder, and a BSD-vs-GNU quote-escape difference. None touch curl.
• shellcheck --severity=error — clean (the gating severity)
• shellcheck --severity=warning — identical finding set to develop, only line numbers shifted. No new warnings.
• bash -n on every *.sh — parses
• bash scripts/check-style.sh — clean; and exits 1 on a planted bare curl
• scripts/gen-manifest.sh --check — up to date (manifest regenerated, R8)
• PowerShell: install-k8s.ps1 parses clean; PSScriptAnalyzer 0 errors, 154 warnings — identical to baseline
• Wrapper exercised under /bin/bash 3.2 with set -euo pipefail (macOS is a supported target): argv shape correct for the plain / stall-bounded / tighter-deadline / no-args cases, exit status propagates
• Real network smoke test through the wrapper (flag combination is valid curl, not just well-formed shell): plain fetch 200, stall-bounded download, HEAD probe

New tests (scripts/tests/common.bats) pin the contract: floor always present, caller args preserved in order, defaults supplied, a caller's own deadline lands after the default, a stall-bounded call gets no --max-time, env overrides, dispatch through a mockable curl, CURL_SECURE still defined.

CI on the first commit

Green across the board — Static analysis, bats, Unit tests, Lint, Pester (ubuntu + windows), all 9 Prereqs distros, 3 E2E cluster legs and E2E auth-proxy. The one red, PATH persist — alpine:3, is an unrelated pre-existing flake: it exercises the cli repo's released install.sh (✖ bash install.sh (SHELL=bash) exited 1 on Alpine v3.24, while zsh and fish passed on the same run), it has failed the same way on at least one other open branch, and nothing in this diff is on its path beyond common.sh's logging helpers — which demonstrably worked, since the job printed its results through them. Re-run requested.

Deployment notes

None. No config, no env vars, no behaviour change on a healthy network. Two new optional knobs (TB_CURL_CONNECT_TIMEOUT, TB_CURL_MAX_TIME) exist for hosts behind unusually slow proxies; both default to the values the bootstrap already hardcodes.

Checklist

• Tests added / updated and passing locally
• Docs updated if behavior or config changed — n/a; the wrapper documents itself in common.sh and the interim check documents its own retirement
• No secrets / credentials in the diff
• For security-sensitive paths: appropriate reviewer requested
• Terminal output follows STYLE.md — bash scripts/check-style.sh passes (and gained a check)

---

Note

Medium Risk
Touches credential verification and all outbound HTTPS in the installer; behavior is mostly additive (TLS floor, timeouts) with careful preservation of stall-bounded large downloads.

Overview
Introduces curl_secure() in common.sh so installer fetches always use --tlsv1.2 plus default connect/max timeouts, while call sites can still tighten deadlines or use stall detection without inheriting a hard --max-time on large binaries.

Routes essentially all scripts/lib/*.sh network pulls through the wrapper (including the credential POST in install-client-helm.sh), adds retry on the AMDGPU .deb download, gives _fetch_kubectl stall bounds so it does not pick up a 300s cap, and spells out the same TLS/timeout flags in the WSL2 NVIDIA toolkit snippet in install-k8s.ps1.

Adds an interimcheck-style.sh rule against bare curl, bats coverage for the wrapper contract and kubectl fetch bounds, and updates manifest.sha256.

^{Reviewed by Cursor Bugbot for commit 0cefb9c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f337c15. Configure here.}

[LukasWodka]

Merge-order note:#401 is stacked on this branch (it fixes an unrelated set -e/pipefail hazard in gpu-amd.sh's _find_package_name, deliberately kept out of this PR to keep it behaviour-neutral). Please merge this one first.

No action needed from the reviewer beyond that — because delete_branch_on_merge is off for this repo, #401 won't auto-retarget, so I'll retarget and rebase it onto develop once this lands.

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 0cefb9c. Configure here.}