From 07373ede4dbc3af405076b13667868979a334663 Mon Sep 17 00:00:00 2001
From: fred <fred@mosaicstack.dev>
Date: Sat, 15 Aug 2026 21:50:14 -0500
Subject: [PATCH] docs(install): record the two trust/portability assumptions
 in install_node
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comment-only, no behaviour change. Both raised by scooby in the #1229 review
as non-blocking findings worth writing down rather than fixing here.

F-A: the SHASUMS256.txt check gives integrity, not authenticity. TLS to
$NODE_DIST_BASE is the whole trust root, and MOSAIC_NODE_DIST_BASE widens it
to any mirror with no signature backstop. GPG-verifying SHASUMS256.txt.sig is
filed as its own follow-up so it gets its own review.

F-C: the uname map pulls the glibc build, so musl hosts fail — visibly, via
node_is_suitable, not silently.
---
 tools/install.sh | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/tools/install.sh b/tools/install.sh
index f6a29833..bd76d265 100755
--- a/tools/install.sh
+++ b/tools/install.sh
@@ -637,6 +637,11 @@ install_node() {
     *) fail "Unsupported OS '$(uname -s)'. Install Node.js >= $NODE_MIN_MAJOR manually."; return 1 ;;
   esac
 
+  # Linux here means glibc. Node's official linux-x64 build is dynamically
+  # linked against glibc, so on musl (Alpine) the binary will not exec — but it
+  # fails visibly: node_is_suitable rejects it and ensure_node exits with
+  # "install Node.js manually". No silent breakage, just a wasted download.
+  # A musl host needs the unofficial build, which is out of scope here.
   case "$(uname -m)" in
     x86_64|amd64)  node_arch="x64" ;;
     aarch64|arm64) node_arch="arm64" ;;
@@ -658,6 +663,13 @@ install_node() {
     rm -rf "$work_dir"; return 1
   fi
 
+  # Trust assumption, stated so nobody has to infer it: this verifies INTEGRITY
+  # (the tarball matches the manifest), not AUTHENTICITY (the manifest is
+  # genuinely Node's). The only thing establishing that is TLS to
+  # $NODE_DIST_BASE. Node publishes SHASUMS256.txt.sig signed by its release
+  # keys and we do not check it, which is on par with nvm but means pointing
+  # MOSAIC_NODE_DIST_BASE at an untrusted mirror has no signature backstop.
+  # Tracked as a hardening follow-up (raised by scooby in the #1229 review).
   if ! curl -fsSL "${release_url}/SHASUMS256.txt" -o "$work_dir/SHASUMS256.txt"; then
     fail "Could not fetch SHASUMS256.txt; refusing to install an unverified runtime."
     rm -rf "$work_dir"; return 1