Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(minikube): close review gaps in the bootstrap link follow-up
Jose Ramirez8cbfc68ee8ea
diff --git a/AGENTS.md b/AGENTS.mdindex 0004a84f1..399a57170 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -86,14 +86,15 @@ profile metadata, logs, and evidence belong under the ignored## Desktop Electron installation invariant-Node 24 ships npm 11, which blocks dependency lifecycle scripts unless they-are explicitly approved. The Desktop app's pinned Electron package is approved-in `desktop-app/package.json` because its `postinstall` downloads the Electron-runtime used by Desktop tests and the local T2 gate. Desktop validation must-use Node 24 (the CI/runtime contract); Node 26 is not a supported validation-runtime for this dependency. Do not install `desktop-app` with-`--ignore-scripts`, and do not count a Desktop test/build result until these-checks succeed from `desktop-app`:+Electron's `postinstall` downloads the runtime used by Desktop tests and the+local T2 gate. When that script does not run, `npm ci` still exits 0 and the+missing runtime only surfaces later as a test failure that looks like a product+bug. Nothing in `package.json` can force the script to run, so the invariant is+enforced by verification rather than by configuration: `npm run verify:electron`+resolves `require('electron')` and fails when the runtime is absent. Desktop+validation must use Node 24, which is the CI and runtime contract. Do not+install `desktop-app` with `--ignore-scripts`, and do not count a Desktop+test/build result until these checks succeed from `desktop-app`:```bashnode --version # must report v24.x@@ -103,8 +104,8 @@ npm run verify:electronIf it fails with `Electron failed to install correctly`, the dependency installis incomplete, not a product failure. Stop the gate, switch to Node 24, removeonly the generated `desktop-app/node_modules/electron` directory, rerun `npm-ci` with lifecycle scripts enabled, and rerun the checks. Do not add broad-script approvals, set `ELECTRON_SKIP_BINARY_DOWNLOAD`, point+ci` with lifecycle scripts enabled, and rerun the checks. Do not set+`ELECTRON_SKIP_BINARY_DOWNLOAD`, point`ELECTRON_OVERRIDE_DIST_PATH` at an unverified binary, or report green evidencefrom a missing runtime. A verified local cache may be used only when itsversion and checksum are recorded in the run evidence.diff --git a/CLAUDE.md b/CLAUDE.mdindex 0214cfd47..aca92b458 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -31,14 +31,14 @@ DSNs, private URLs, or raw request/response bodies.## Desktop Electron runtime-Node 24 uses npm 11, whose install-script approval model can leave Electron-without its downloaded runtime while `npm ci` still exits successfully. The-pinned Electron package is explicitly approved in `desktop-app/package.json`.-Desktop validation must use Node 24 (Node 26 is not a supported validation-runtime), run `npm ci` without `--ignore-scripts`, and verify-`npm run verify:electron` confirms that `require('electron')` resolves to an-executable before any test/build result is counted. If the check reports `Electron failed to install correctly`, switch to-Node 24, repair the generated dependency directory, and rerun the install;-never bypass the postinstall with `ELECTRON_SKIP_BINARY_DOWNLOAD`, use an+A skipped Electron `postinstall` leaves the runtime undownloaded while `npm ci`+still exits successfully, so the failure surfaces later as a test error that+looks like a product bug. No `package.json` field prevents this; the guard is+`npm run verify:electron`, which fails when `require('electron')` does not+resolve to an executable. Desktop validation must use Node 24, run `npm ci`+without `--ignore-scripts`, and pass that check before any test/build result is+counted. If the check reports `Electron failed to install correctly`, switch to+Node 24, repair the generated dependency directory, and rerun the install.+Never bypass the postinstall with `ELECTRON_SKIP_BINARY_DOWNLOAD`, use anunverified override, or treat the resulting test failure as a productregression.diff --git a/desktop-app/package.json b/desktop-app/package.jsonindex 13435a381..b11d21ddf 100644--- a/desktop-app/package.json+++ b/desktop-app/package.json@@ -86,8 +86,5 @@"@tootallnate/once": "^3.0.1","tmp": "^0.2.4","tar": "7.5.19"- },- "allowScripts": {- "[email protected]": true}}diff --git a/desktop-app/scripts/verify-electron-runtime.mjs b/desktop-app/scripts/verify-electron-runtime.mjsindex 8e51fd565..861b9e187 100644--- a/desktop-app/scripts/verify-electron-runtime.mjs+++ b/desktop-app/scripts/verify-electron-runtime.mjs@@ -1,6 +1,29 @@-import electronPath from 'electron'import fs from 'node:fs'+// Desktop validation is the one place the Node major is contractual: the+// Electron postinstall and the prebuilt runtime are matched to Node 24, and CI+// pins node-version 24. The quickstart prereq check only enforces a >= 24+// floor, so assert the exact major here instead of blocking the whole install.+// This runs before Electron is imported: a static import hoists above the check+// and would report ERR_MODULE_NOT_FOUND on a wrong runtime instead of saying so.+const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10)+if (nodeMajor !== 24) {+ throw new Error(+ `Desktop validation requires Node 24.x; found v${process.versions.node}. ` ++ 'Switch to Node 24 and rerun npm ci with lifecycle scripts enabled.'+ )+}++let electronPath+try {+ electronPath = (await import('electron')).default+} catch (cause) {+ throw new Error(+ 'Electron is not installed; run npm ci with lifecycle scripts enabled (never --ignore-scripts)',+ { cause }+ )+}+const runtimePath = typeof electronPath === 'string' ? electronPath : ''if (!runtimePath) {throw new Error('Electron runtime path is unavailable; run npm ci with lifecycle scripts enabled')diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.mdindex 2e90b86db..01d14e82c 100644--- a/docs/get-started/minikube.md+++ b/docs/get-started/minikube.md@@ -10,7 +10,7 @@ single LLM key you set in `.env`.## PrerequisitesDocker Desktop with **≥10 GB RAM / 6 CPUs** · `minikube` v1.30+ · `kubectl` ·-`python3` · Node.js 24.x · `git` · `make` · `ruby` (renders the control-api DB+`python3` · Node.js 24+ · `git` · `make` · `ruby` (renders the control-api DBmigration overlay; ships with macOS, `apt-get install ruby` on Debian/Ubuntu).Run `make prereqs` (alias `make doctor`) to check every one of these at once —diff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.shindex adff1b4fd..bfddc8c2b 100755--- a/scripts/check-prereqs.sh+++ b/scripts/check-prereqs.sh@@ -91,19 +91,27 @@ elseMISSING=$((MISSING + 1))fi-# ── Node.js 24.x (Desktop/Electron validation contract) ───────────────+# ── Node.js (>= 24; Desktop/Electron validation wants 24.x) ───────────+# The platform itself runs in containers, so the quickstart only needs a+# floor here. Pinning the whole install to 24.x would lock out newer runtimes+# for a Desktop-only concern. Desktop validation is where 24.x is contractual:+# CI pins node-version 24 and desktop-app/scripts/verify-electron-runtime.mjs+# enforces it before any Desktop test/build result counts.if command -v node >/dev/null 2>&1; thenNODE_VER="$(node --version | sed 's/^v//')"NODE_MAJOR="${NODE_VER%%.*}"- if [ "$NODE_MAJOR" = "24" ]; then+ if version_ge "$NODE_VER" "24.0.0"; thenok "node v${NODE_VER}"+ if [ "$NODE_MAJOR" != "24" ]; then+ warn "node v${NODE_VER} runs the quickstart, but Desktop/Electron validation requires 24.x"+ fielse- err "node v${NODE_VER} (need 24.x for Desktop/Electron validation)"+ err "node v${NODE_VER} (need >= 24)"hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"MISSING=$((MISSING + 1))fielse- err "node not found (need 24.x for Desktop/Electron validation)"+ err "node not found (need >= 24)"hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"MISSING=$((MISSING + 1))fidiff --git a/scripts/e2e/seed-e2e-data.sh b/scripts/e2e/seed-e2e-data.shindex 7c58eb124..1afa9fee8 100755--- a/scripts/e2e/seed-e2e-data.sh+++ b/scripts/e2e/seed-e2e-data.sh@@ -538,7 +538,13 @@ verify_minimal_operator_bootstrap() {link_admin_id="$(echo "$ADMIN_GET_BODY" | jq -r --arg username "$ADMIN_USERNAME" --arg email "$ADMIN_EMAIL" \'.admins[] | select(.username == $username and ((.email // "") | ascii_downcase) == $email) | .gfsOperatorLink.controlAdminId // empty')"if ! clerum_initial_setup_link_matches "$status" "$source" "$desktop_user_id" "$link_admin_id" "$admin_id"; then- die "Minimal bootstrap is incomplete: expected one active initial_setup Desktop link for '$ADMIN_EMAIL' (status=$status source=$source desktopUserId=${desktop_user_id:-missing} controlAdminId=${link_admin_id:-missing}); refusing ordinary-user fallback"+ # Recovery is only possible by rebuilding the control DB. control-api+ # stamps last_login_at on every successful admin login and+ # setupInitialAdminCredentials only matches a bootstrap row whose+ # last_login_at is still NULL, so once a cluster has logged in without+ # consuming setup the initial_setup link can never be created on that+ # database. Say so instead of leaving the operator with a bare refusal.+ die "Minimal bootstrap is incomplete: expected one active initial_setup Desktop link for '$ADMIN_EMAIL' (status=$status source=$source desktopUserId=${desktop_user_id:-missing} controlAdminId=${link_admin_id:-missing}); refusing ordinary-user fallback. This cluster consumed or bypassed /admin/auth/setup without creating the link, and it cannot be created on the existing database. Rebuild the control DB to recover: re-run 'make minikube-setup' without REUSE_DB/--keep-db (the default rebuilds the DB), passing CONTROL_DB_RESET_PVC_UID when the setup script asks for it."fiok "Initial admin '$ADMIN_USERNAME' has active initial_setup Desktop operator link (desktopUserId=${desktop_user_id:0:8}…)"}diff --git a/scripts/minikube/full-setup.sh b/scripts/minikube/full-setup.shindex 858526e4a..1baa901d1 100755--- a/scripts/minikube/full-setup.sh+++ b/scripts/minikube/full-setup.sh@@ -1470,9 +1470,13 @@ else# from it on every fresh DB. If this step fails under the default# (minimal) profile, that publicly-known credential is still live — a# green summary would ship an install that is both unusable and insecure.- # Abort instead; setup is idempotent, so re-running after the underlying- # issue is fixed recovers cleanly.- err "Test user seed failed under SEED_PROFILE=minimal — aborting. The bootstrap admin password may still be the publicly-known default (see generate-keys.sh) until this step succeeds. Fix the error above and re-run setup."+ # Abort instead. Setup is idempotent, so re-running after the underlying+ # issue is fixed recovers cleanly for every failure except a missing+ # initial_setup link on a reused database: control-api stamps+ # last_login_at on each admin login and setup only matches a bootstrap+ # row whose last_login_at is NULL, so that one needs a DB rebuild. The+ # seeder prints the exact recovery command for that case.+ err "Test user seed failed under SEED_PROFILE=minimal, aborting. The bootstrap admin password may still be the publicly-known default (see generate-keys.sh) until this step succeeds. Fix the error above and re-run setup. If the seeder reported a missing initial_setup Desktop link, re-run without REUSE_DB/--keep-db so the control DB is rebuilt."exit 1elsewarn "Test user seed encountered errors — check output above"diff --git a/scripts/tests/test-minikube-full-setup.sh b/scripts/tests/test-minikube-full-setup.shindex 5b5d83865..50af50d78 100755--- a/scripts/tests/test-minikube-full-setup.sh+++ b/scripts/tests/test-minikube-full-setup.sh@@ -520,17 +520,47 @@ assert_bootstrap_seed_deferral_rejects_non_local_or_e2e_modes() {assert_minimal_seed_is_setup_first_and_link_fail_closed() {local seed="$REPO_ROOT/scripts/e2e/seed-e2e-data.sh"- local minimal_block- minimal_block="$(sed -n '/^if \[ "\$SEED_PROFILE" = "minimal" \]; then$/,/^else$/p' "$seed")"- if printf '%s\n' "$minimal_block" | grep -Fq 'perform_initial_setup' && \- printf '%s\n' "$minimal_block" | grep -Fq 'login_admin_only' && \- printf '%s\n' "$minimal_block" | grep -Fq 'verify_minimal_operator_bootstrap' && \- grep -Fq 'clerum_initial_setup_link_matches' "$seed" && \- grep -Fq 'refusing ordinary-user fallback' "$seed"; then- pass "minimal seed consumes setup before login and fails closed without an active initial_setup link"- else- fail "minimal seed does not prove setup-first ordering and fail-closed link verification"+ local dispatch verify_body setup_line login_line verify_line++ # Bound the dispatch and the verifier exactly. A range that ends at the first+ # bare `else` runs past every nested block and swallows most of the file, so+ # presence greps alone still pass when the ordering is reversed or the+ # fail-closed abort is downgraded to a warning.+ dispatch="$(awk '/^# ─── Step 1: Bootstrap before login/,/^fi$/' "$seed")"+ verify_body="$(awk '/^verify_minimal_operator_bootstrap\(\) \{$/,/^\}$/' "$seed")"++ setup_line="$(printf '%s\n' "$dispatch" | grep -n '^ perform_initial_setup$' | head -1 | cut -d: -f1)"+ login_line="$(printf '%s\n' "$dispatch" | grep -n 'login_admin_only' | head -1 | cut -d: -f1)"+ verify_line="$(printf '%s\n' "$dispatch" | grep -n '^ verify_minimal_operator_bootstrap$' | head -1 | cut -d: -f1)"++ if [ -z "$setup_line" ] || [ -z "$login_line" ] || [ -z "$verify_line" ]; then+ fail "minimal seed dispatch must call setup, the login fallback and link verification"+ return+ fi+ # control-api marks last_login_at on every successful admin login, and+ # setupInitialAdminCredentials only matches a bootstrap row whose+ # last_login_at is still NULL. Logging in first destroys setup eligibility+ # permanently, so this ordering is the whole point of the minimal path.+ if [ "$setup_line" -ge "$login_line" ]; then+ fail "minimal seed logs in at line $login_line before consuming setup at line $setup_line; login sets last_login_at and permanently disqualifies /admin/auth/setup"+ return+ fi+ if [ "$verify_line" -le "$login_line" ]; then+ fail "minimal seed must verify the initial_setup link after the login fallback, not before it"+ return+ fi+ if ! printf '%s\n' "$verify_body" | grep -Fq 'if ! clerum_initial_setup_link_matches '; then+ fail "minimal link verification does not gate on the shared initial_setup link contract"+ return+ fi+ # The missing-link branch must abort. Downgrading it to a log leaves the+ # install running as an ordinary unlinked member, which is the exact+ # regression this assertion exists to catch.+ if ! printf '%s\n' "$verify_body" | grep -Eq '^ *die "Minimal bootstrap is incomplete'; then+ fail "minimal link verification does not abort when the initial_setup link is absent"+ returnfi+ pass "minimal seed consumes setup before login and aborts without an active initial_setup link"}assert_minimal_bootstrap_contract_runs_on_system_bash() {