Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(gateway): close final lifecycle boundaries
Rahman46e75286f0d9
diff --git a/README.md b/README.mdindex 9a351187..45eecc12 100644--- a/README.md+++ b/README.md@@ -205,8 +205,9 @@ mso gateway stopTemporary mode uses a Cloudflare Quick Tunnel and does **not** change `OS_PUBLIC_ORIGIN`, theMSO bind address, router/NAT rules, or the Windows firewall. The normal password + approved-devicegate, live device roles, Secure/HttpOnly/SameSite cookie, same-origin mutation gate, CSP and login-rate limits remain in front of the host APIs. Gateway state/logs live under owner-only-`~/.mso/private/gateway`; `stop` validates process identity before terminating anything. On first use, MSO downloads the reviewed `cloudflared` release pinned in+rate limits remain in front of the host APIs. Gateway state/logs live under an owner-only+checkout+loopback-origin namespace below `~/.mso/private/gateway`, so two clones/ports cannot control+each other's tunnel. `stop` validates process identity before terminating anything. On first use, MSO downloads the reviewed `cloudflared` release pinned in`security/gateway-artifacts.env` into user-local `~/.mso/tools`, verifies its SHA-256 before firstexecution and again before every reuse, and passes `--no-autoupdate`. No root package install,mutable `latest`, or `curl | sh` is involved. Use `mso gateway install` to prefetch it explicitly.diff --git a/SECURITY.md b/SECURITY.mdindex e919bc55..6eb8f26f 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -35,8 +35,11 @@ application roles, but they still share the same deployment and underlying Unix- Gateway/update lifecycle state is owner-only and fail-closed: public tunneling requires verifiedloopback-only exposure; offline recovery uses checkout-scoped receipts, an exclusive process-identitylock, and durable pre-quiesce recovery intent rather than treating Git HEAD as deployment proof.- Tunnel startup additionally uses a parent/child release handshake, so Cloudflared cannot execute- before its process lifetime is tracked; interruption before release makes the held child self-exit.+ Tunnel and fallback-runtime startup additionally use a parent/child release handshake, so neither+ Cloudflared nor Next can execute before its process lifetime is tracked; interruption before release+ makes the held child self-exit. Gateway state is namespaced by canonical checkout + loopback origin,+ lifecycle/update serialization uses crash-released kernel `flock`, and public readiness must match+ the exact local build/runtime identity rather than only the MSO version.- Use `NEXT_PUBLIC_OS_DEMO=1` only in a separate mock-only public demo checkout.The core gateway client follows the same immutable-artifact rule as managed apps: MSO pins thediff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex ee69255b..ee71d80d 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -13,6 +13,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `gateway` close final lifecycle boundaries- `gateway` close tunnel fork signal race- `gateway` serialize offline recovery state- `gateway` harden update and proxy edgesdiff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 11a29761..eafd9cee 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -14,6 +14,7 @@- a non-root user that owns MSO;- enough memory/swap for a Next production build (build needs more than idle runtime);- HTTPS through Tailscale Serve or a reverse proxy for normal non-localhost browser use.+- CLI runtime tools `curl`, `jq`, GNU coreutils and util-linux `flock` (the installer adds missing packages on supported package managers).Optional Browser support additionally needs Camoufox, Xvfb, a lightweight X window manager,x11vnc, noVNC/websockify and a user systemd runtime.@@ -164,7 +165,13 @@ never changes the application bind to `0.0.0.0`. The tool cache is user-local anwith Cloudflare auto-update disabled. The tunnel process also receives a scrubbed environment ratherthan inheriting MSO login/session/BYOK secrets from the application shell. If systemd is unavailable (common on WSL), it may start thealready-built Next production runtime itself, still on `127.0.0.1`, and records whether that process-is gateway-owned. `gateway stop` terminates only recorded identities: Cloudflared is matched by PID/start-time/executable/exact argv, while the Next fallback uses PID/start-time/Node executable plus a random runtime-instance nonce echoed by `/api/health` so Next's mutable process title cannot confuse ownership. Private state and logs are owner-only.+is gateway-owned. `gateway stop` terminates only recorded identities: Cloudflared is matched by PID/start-time/executable/exact argv, while the Next fallback uses PID/start-time/Node executable plus a random runtime-instance nonce echoed by `/api/health` so Next's mutable process title cannot confuse ownership. Private state and logs are owner-only and scoped by the canonical checkout plus selected loopback+origin. The fallback Next process uses the same held-child release handshake as Cloudflared, so neither+child may execute before the parent records PID + kernel start-ticks. Gateway/update lifecycle+transactions use kernel `flock`, which is released automatically when a process exits instead of+trying to reclaim stale lock directories. Before a public tunnel is accepted, MSO snapshots the+selected local `{version, buildId, runtimeInstanceId}` and requires the HTTPS endpoint to return the+exact same identity; a same-version deployment routed from the wrong hostname is rejected.This is intentionally labeled **temporary preview**. The random `trycloudflare.com` URL changes onrestart, and Cloudflare Quick Tunnels do not support Server-Sent Events; MSO Terminal's live outputdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex ffbe20cf..e04ebc40 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -36,7 +36,11 @@ writer now propagates write/rename failures explicitly even when called from a sfull pre-push run then exposed a fork/signal race before the tunnel fingerprint existed. Tunnel launchnow uses a held-child handshake: the scrubbed child cannot `exec cloudflared` until its parent recordsPID + kernel start-ticks and releases an owner-only gate; if the parent disappears first, the child-self-terminates. This closes the last pre-persistence orphan window without weakening process identity.+self-terminates. The same handshake now protects the detached Next fallback. Final review also moved+gateway/update serialization to kernel `flock` (no stale-lock ABA reclaim), scoped gateway state by+canonical checkout + selected loopback origin, and made public readiness compare the exact local+`version + buildId + runtimeInstanceId`. This closes the cross-clone control and wrong-deployment+readiness classes without widening the raw app bind.The global response policy additionally sends `X-Robots-Tag: noindex, nofollow, noarchive` because anMSO control plane should not be indexed merely because a temporary HTTPS endpoint exists. Thediff --git a/lib/install-contract.test.ts b/lib/install-contract.test.tsindex 712c30c4..f6c0a751 100644--- a/lib/install-contract.test.ts+++ b/lib/install-contract.test.ts@@ -118,7 +118,8 @@ describe("one-line installer contract", () => {expect(src).toContain('export PATH="$BIN_DIR:$PATH"');expect(src).toContain('custom MSO_BIN_DIR is not persisted automatically');expect(src).toContain("ensure_cli_tools()");- expect(src).toContain("curl jq coreutils");+ expect(src).toContain("curl jq coreutils util-linux");+ expect(src).toContain("sha256sum flock");expect(src).toContain('[ -x "$BIN_DIR/mso" ]');expect(src).toContain('CLI launcher self-check failed');});diff --git a/scripts/install-core.sh b/scripts/install-core.shindex 708b8338..603b1499 100755--- a/scripts/install-core.sh+++ b/scripts/install-core.sh@@ -278,20 +278,21 @@ ensure_buildtools() {}ensure_cli_tools() {- # bin/mso uses jq for JSON shaping and coreutils for guarded file identity.+ # bin/mso uses jq for JSON shaping, coreutils for guarded file identity, and+ # util-linux flock for crash-safe gateway/update transaction locks.# A pristine WSL/Ubuntu image may have Node+Bun but no jq. Install these before# creating the launcher so `mso -h` is a real installer postcondition.local missing=0 tool- for tool in curl jq realpath stat mktemp sha256sum; do+ for tool in curl jq realpath stat mktemp sha256sum flock; docommand -v "$tool" >/dev/null 2>&1 || { missing=1; break; }done[ "$missing" -eq 0 ] && return- info "installing CLI runtime tools (curl, jq, coreutils)…"- if command -v apt-get >/dev/null 2>&1; then sudo_do apt-get update -qq && sudo_do apt-get install -y -qq curl jq coreutils- elif command -v dnf >/dev/null 2>&1; then sudo_do dnf install -y -q curl jq coreutils- elif command -v pacman >/dev/null 2>&1; then sudo_do pacman -Sy --noconfirm curl jq coreutils- else die "mso CLI needs curl, jq, realpath, stat, mktemp and sha256sum; install the missing tools, then rerun."; fi- for tool in curl jq realpath stat mktemp sha256sum; do+ info "installing CLI runtime tools (curl, jq, coreutils, util-linux)…"+ if command -v apt-get >/dev/null 2>&1; then sudo_do apt-get update -qq && sudo_do apt-get install -y -qq curl jq coreutils util-linux+ elif command -v dnf >/dev/null 2>&1; then sudo_do dnf install -y -q curl jq coreutils util-linux+ elif command -v pacman >/dev/null 2>&1; then sudo_do pacman -Sy --noconfirm curl jq coreutils util-linux+ else die "mso CLI needs curl, jq, realpath, stat, mktemp, sha256sum and flock; install the missing tools, then rerun."; fi+ for tool in curl jq realpath stat mktemp sha256sum flock; docommand -v "$tool" >/dev/null 2>&1 || die "CLI runtime dependency still missing after package install: $tool"done}diff --git a/scripts/install.sh b/scripts/install.shindex 140c30a3..7152fe5c 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -12,7 +12,7 @@ set -Eeuo pipefailumask 077CORE_URL="${MSO_INSTALL_CORE_URL:-https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-core.sh}"-CORE_SHA256="59da7270bc2a86ee319b8c7bab7314efd186e232538bc487ab320c81c8ef24b6"+CORE_SHA256="c21f72acd477edd2a60062efbe3b735f24ddcd0b46a7db60f0cd0900428fbc5d"CORE_EOF='# MSO_INSTALLER_CORE_EOF'TMP_INSTALLER=''diff --git a/scripts/lib/gateway-common.sh b/scripts/lib/gateway-common.shindex 2bde57fd..fc7910d5 100644--- a/scripts/lib/gateway-common.sh+++ b/scripts/lib/gateway-common.sh@@ -41,6 +41,7 @@ gateway_private_file() {}gateway_state_read() {+ local state scope local_urlif [ -e "$STATE_FILE" ] || [ -L "$STATE_FILE" ]; thenif ! mso_private_state_validate_file "$STATE_FILE" >/dev/null; thenprintf 'mso gateway: unsafe gateway state file\n' >&2; return 2@@ -48,9 +49,15 @@ gateway_state_read() {if [ ! -s "$STATE_FILE" ]; thenprintf 'mso gateway: gateway state is empty; inspect %s before removing it\n' "$STATE_FILE" >&2; return 2fi- if ! jq -e . "$STATE_FILE" 2>/dev/null; then- printf 'mso gateway: gateway state is corrupt; inspect %s before removing it\n' "$STATE_FILE" >&2; return 2+ state="$(jq -ce . "$STATE_FILE" 2>/dev/null)" || {+ printf 'mso gateway: gateway state is corrupt; inspect %s before removing it\n' "$STATE_FILE" >&2; return 2;+ }+ scope="$(jq -r '.scopeId // empty' <<<"$state")"+ local_url="$(jq -r '.localUrl // empty' <<<"$state")"+ if [ "$scope" != "$GATEWAY_SCOPE_ID" ] || [ "$local_url" != "$LOCAL_URL" ]; then+ printf 'mso gateway: gateway state belongs to another checkout/origin; refusing reuse\n' >&2; return 2fi+ printf '%s\n' "$state"elseprintf '{}\n'fi@@ -150,32 +157,3 @@ gateway_stop_identity() {donegateway_identity_matches "$identity" && kill -KILL "$pid" 2>/dev/null || true}--gateway_health_body_ok() {- local body="$1" expected_instance="${2-}"- [ -n "$body" ] || return 1- jq -e --arg version "$GATEWAY_EXPECTED_VERSION" --arg instance "$expected_instance" '- type == "object" and .status == "ok" and .version == $version and- (.buildId | type == "string") and (.buildId | length > 0) and- (if $instance == "" then has("runtimeInstanceId") else .runtimeInstanceId == $instance end)- ' <<<"$body" >/dev/null 2>&1-}--gateway_health_url_ok() {- local base="$1" expected_instance="${2-}" body loopback- local -a curl_args=(-fsS --max-time 4)- loopback="$(gateway_validate_loopback_origin "$base" 2>/dev/null || true)"- # A user's http_proxy/HTTP_PROXY must never redirect the trusted local-health- # decision through a proxy. Public HTTPS probes retain ordinary proxy behavior.- [ -z "$loopback" ] || curl_args+=(--noproxy '*')- body="$("$CURL" "${curl_args[@]}" "$base/api/health" 2>/dev/null || true)"- gateway_health_body_ok "$body" "$expected_instance"-}--gateway_health_ok() { gateway_health_url_ok "$LOCAL_URL"; }--gateway_wait_health() {- local expected_instance="${1-}" i- for i in $(seq 1 40); do gateway_health_url_ok "$LOCAL_URL" "$expected_instance" && return 0; sleep 0.25; done- return 1-}diff --git a/scripts/lib/gateway-health.sh b/scripts/lib/gateway-health.shnew file mode 100755index 00000000..42a90c98--- /dev/null+++ b/scripts/lib/gateway-health.sh@@ -0,0 +1,54 @@+#!/usr/bin/env bash+# Structured MSO health identity fetch/match helpers.++gateway_health_body_ok() {+ local body="$1" expected_instance="${2-}"+ [ -n "$body" ] || return 1+ jq -e --arg version "$GATEWAY_EXPECTED_VERSION" --arg instance "$expected_instance" '+ type == "object" and .status == "ok" and .version == $version and+ (.buildId | type == "string") and (.buildId | length > 0) and has("runtimeInstanceId") and+ (if $instance == "" then true else .runtimeInstanceId == $instance end)+ ' <<<"$body" >/dev/null 2>&1+}++gateway_health_identity_from_body() {+ local body="$1" expected_instance="${2-}"+ gateway_health_body_ok "$body" "$expected_instance" || return 1+ jq -c '{version,buildId,runtimeInstanceId}' <<<"$body"+}++gateway_fetch_health_body() {+ local base="$1" loopback+ local -a curl_args=(-fsS --max-time 4)+ loopback="$(gateway_validate_loopback_origin "$base" 2>/dev/null || true)"+ [ -z "$loopback" ] || curl_args+=(--noproxy '*')+ "$CURL" "${curl_args[@]}" "$base/api/health" 2>/dev/null+}++gateway_health_url_identity() {+ local body+ body="$(gateway_fetch_health_body "$1" 2>/dev/null || true)"+ gateway_health_identity_from_body "$body" "${2-}"+}++gateway_health_url_ok() { gateway_health_url_identity "$1" "${2-}" >/dev/null; }++gateway_health_body_matches_identity() {+ local actual+ actual="$(gateway_health_identity_from_body "$1" 2>/dev/null || true)"+ [ -n "$actual" ] && [ "$actual" = "$2" ]+}++gateway_health_url_matches_identity() {+ local actual+ actual="$(gateway_health_url_identity "$1" 2>/dev/null || true)"+ [ -n "$actual" ] && [ "$actual" = "$2" ]+}++gateway_health_ok() { gateway_health_url_ok "$LOCAL_URL"; }++gateway_wait_health() {+ local expected_instance="${1-}" i+ for i in $(seq 1 40); do gateway_health_url_ok "$LOCAL_URL" "$expected_instance" && return 0; sleep 0.25; done+ return 1+}diff --git a/scripts/lib/gateway-lock.sh b/scripts/lib/gateway-lock.shindex b97d3c61..4b3b2372 100755--- a/scripts/lib/gateway-lock.sh+++ b/scripts/lib/gateway-lock.sh@@ -1,36 +1,24 @@#!/usr/bin/env bash# Owner-only lifecycle lock and signal-safe pending-child cleanup.-gateway_lock_owner_valid() {- local owner="$LOCK_DIR/owner" pid ticks live- [ -f "$owner" ] && [ ! -L "$owner" ] || return 1- read -r pid ticks <"$owner" || return 1- [[ "$pid" =~ ^[0-9]+$ && "$ticks" =~ ^[0-9]+$ ]] || return 1- live="$(gateway_proc_start_ticks "$pid" 2>/dev/null || true)"- [ -n "$live" ] && [ "$live" = "$ticks" ]-}-gateway_lock_acquire() {- local self_ticks candidate stale i- self_ticks="$(gateway_proc_start_ticks $$)" || gateway_fail "cannot identify gateway process"- for i in $(seq 1 240); do- candidate="$STATE_ROOT/.lifecycle-lock.$$.$RANDOM"- mkdir -m 700 -- "$candidate"- printf '%s %s\n' "$$" "$self_ticks" >"$candidate/owner"; chmod 600 "$candidate/owner"- if mv -T -- "$candidate" "$LOCK_DIR" 2>/dev/null; then LOCK_HELD=1; return 0; fi- rm -rf -- "$candidate"- if [ -d "$LOCK_DIR" ] && [ ! -L "$LOCK_DIR" ] && ! gateway_lock_owner_valid; then- stale="$STATE_ROOT/.lifecycle-stale.$$.$RANDOM"- mv -T -- "$LOCK_DIR" "$stale" 2>/dev/null && rm -rf -- "$stale" || true- fi- sleep 0.05- done- gateway_fail "another gateway lifecycle operation is still running"+ gateway_private_file "$LOCK_FILE"+ exec {GATEWAY_LOCK_FD}<>"$LOCK_FILE" || gateway_fail "cannot open gateway lifecycle lock"+ if ! flock -x -w 12 "$GATEWAY_LOCK_FD"; then+ exec {GATEWAY_LOCK_FD}>&- || true+ GATEWAY_LOCK_FD=''+ gateway_fail "another gateway lifecycle operation is still running"+ fi+ LOCK_HELD=1}gateway_lock_release() {[ "${LOCK_HELD:-0}" = 1 ] || return 0- if gateway_lock_owner_valid; then rm -f -- "$LOCK_DIR/owner"; rmdir -- "$LOCK_DIR" 2>/dev/null || true; fi+ if [ -n "${GATEWAY_LOCK_FD:-}" ]; then+ flock -u "$GATEWAY_LOCK_FD" 2>/dev/null || true+ exec {GATEWAY_LOCK_FD}>&- || true+ GATEWAY_LOCK_FD=''+ fiLOCK_HELD=0}diff --git a/scripts/lib/gateway-recovery.sh b/scripts/lib/gateway-recovery.shindex 3e054dc2..e73c0008 100755--- a/scripts/lib/gateway-recovery.sh+++ b/scripts/lib/gateway-recovery.sh@@ -43,3 +43,43 @@ gateway_wait_runtime_stopped() {donereturn 1}++RUNTIME_PENDING_PID=0+RUNTIME_PENDING_TICKS=''+RUNTIME_PENDING_GATE=''++gateway_track_pending_runtime() {+ local pid="$1" ticks i+ RUNTIME_PENDING_PID="$pid"; RUNTIME_PENDING_TICKS=''+ for i in $(seq 1 20); do+ ticks="$(gateway_proc_start_ticks "$pid" 2>/dev/null || true)"+ [ -n "$ticks" ] && { RUNTIME_PENDING_TICKS="$ticks"; GATEWAY_PENDING_CLEANUP=1; return 0; }+ gateway_pid_alive "$pid" || return 1+ sleep 0.01+ done+ return 1+}++gateway_runtime_pending_gate_cleanup() {+ local gate="${RUNTIME_PENDING_GATE:-}"+ [ -n "$gate" ] || return 0+ if [ -e "$gate" ] || [ -L "$gate" ]; then mso_private_state_remove_file "$gate" >/dev/null 2>&1 || true; fi+ RUNTIME_PENDING_GATE=''+}++gateway_stop_pending_runtime() {+ local pid="${RUNTIME_PENDING_PID:-0}" ticks="${RUNTIME_PENDING_TICKS:-}" live i+ gateway_runtime_pending_gate_cleanup+ [ "$pid" -gt 1 ] 2>/dev/null && [ -n "$ticks" ] || return 0+ live="$(gateway_proc_start_ticks "$pid" 2>/dev/null || true)"+ [ "$live" = "$ticks" ] || { RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''; return 0; }+ kill "$pid" 2>/dev/null || true+ for i in $(seq 1 25); do+ live="$(gateway_proc_start_ticks "$pid" 2>/dev/null || true)"+ [ "$live" != "$ticks" ] && break+ sleep 0.04+ done+ live="$(gateway_proc_start_ticks "$pid" 2>/dev/null || true)"+ [ "$live" != "$ticks" ] || kill -KILL "$pid" 2>/dev/null || true+ RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''+}diff --git a/scripts/lib/gateway-runtime.sh b/scripts/lib/gateway-runtime.shindex 99222a01..142e9e06 100644--- a/scripts/lib/gateway-runtime.sh+++ b/scripts/lib/gateway-runtime.sh@@ -16,7 +16,7 @@ gateway_runtime_from_state() {}gateway_start_runtime_if_needed() {- local next host port pid identity instance node_exe current_exe i+ local next host port pid identity instance node_exe current_exe i parent_ticks gate[ "$RUNTIME_OWNED" = true ] && gateway_health_url_ok "$LOCAL_URL" "$RUNTIME_INSTANCE_ID" && return 0if gateway_health_ok; thenRUNTIME_IDENTITY='null'; RUNTIME_INSTANCE_ID=''; RUNTIME_OWNED=false; RUNTIME_STARTED_NOW=false@@ -34,12 +34,20 @@ gateway_start_runtime_if_needed() {instance="$(node -e 'process.stdout.write(require("crypto").randomBytes(16).toString("hex"))')"node_exe="$(readlink -f -- "$(command -v node)")"gateway_private_file "$RUNTIME_LOG"; : >"$RUNTIME_LOG"+ parent_ticks="$(gateway_proc_start_ticks $$)" || gateway_fail "cannot identify runtime-launch parent"+ gate="$STATE_ROOT/.runtime-release.$$.$RANDOM"+ RUNTIME_PENDING_GATE="$gate"; RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''(cd "$ROOT" || exit 1- nohup env MSO_RUNTIME_INSTANCE_ID="$instance" node "$next" start --hostname 127.0.0.1 --port "$port" >>"$RUNTIME_LOG" 2>&1 &+ nohup /bin/bash "$ROOT/scripts/lib/gateway-held-child.sh" "$$" "$parent_ticks" "$gate" \+ env MSO_RUNTIME_INSTANCE_ID="$instance" node "$next" start --hostname 127.0.0.1 --port "$port" \+ >>"$RUNTIME_LOG" 2>&1 &printf '%s\n' "$!") >"$STATE_ROOT/.runtime-pid.$$"pid="$(cat "$STATE_ROOT/.runtime-pid.$$")"; rm -f "$STATE_ROOT/.runtime-pid.$$"+ gateway_track_pending_runtime "$pid" || { kill "$pid" 2>/dev/null || true; gateway_runtime_pending_gate_cleanup; gateway_fail "runtime held child could not be tracked"; }+ printf '1\n' | mso_private_state_atomic_write "$gate" >/dev/null \+ || { gateway_stop_pending_runtime; gateway_fail "runtime release gate could not be persisted"; }identity=''for i in $(seq 1 30); doif gateway_pid_alive "$pid"; then@@ -51,22 +59,25 @@ gateway_start_runtime_if_needed() {else break; fisleep 0.05done- if [ -z "$identity" ]; then kill "$pid" 2>/dev/null || true; gateway_fail "runtime did not start as the expected Node process"; fi+ if [ -z "$identity" ]; then gateway_stop_pending_runtime; gateway_fail "runtime did not start as the expected Node process"; fi+ gateway_runtime_pending_gate_cleanupidentity="$(jq -c --arg instance "$instance" '.cmdHash=null | .instanceId=$instance' <<<"$identity")"if ! gateway_wait_health "$instance"; thengateway_stop_identity "$identity"gateway_fail "runtime did not become this launch's MSO health instance; see $RUNTIME_LOG"fiRUNTIME_IDENTITY="$identity"; RUNTIME_INSTANCE_ID="$instance"; RUNTIME_OWNED=true; RUNTIME_STARTED_NOW=true+ RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''GATEWAY_PENDING_CLEANUP=1}gateway_write_state() {local provider="$1" mode="$2" url="$3" tunnel_identity="$4"- jq -nc --arg provider "$provider" --arg mode "$mode" --arg url "$url" --arg local "$LOCAL_URL" \+ jq -nc --arg scopeId "$GATEWAY_SCOPE_ID" --arg root "$GATEWAY_CANONICAL_ROOT" \+ --arg provider "$provider" --arg mode "$mode" --arg url "$url" --arg local "$LOCAL_URL" \--argjson tunnelIdentity "$tunnel_identity" --argjson runtimeIdentity "$RUNTIME_IDENTITY" \--argjson runtimeOwned "$RUNTIME_OWNED" --arg startedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \- '{provider:$provider,mode:$mode,url:$url,localUrl:$local,tunnelIdentity:$tunnelIdentity,+ '{scopeId:$scopeId,root:$root,provider:$provider,mode:$mode,url:$url,localUrl:$local,tunnelIdentity:$tunnelIdentity,runtimeIdentity:$runtimeIdentity,runtimeOwned:$runtimeOwned,startedAt:$startedAt}' \| mso_private_state_atomic_write "$STATE_FILE" >/dev/null}diff --git a/scripts/lib/gateway-tunnel.sh b/scripts/lib/gateway-tunnel.shindex 90f84980..88547f79 100644--- a/scripts/lib/gateway-tunnel.sh+++ b/scripts/lib/gateway-tunnel.sh@@ -127,7 +127,7 @@ gateway_quick_edge_health_ok() {# random trycloudflare hostname, and the body must match this launch's nonce.body="$("$CURL" -fsS --max-time 5 --resolve "$host:443:$ip" \"$GATEWAY_PUBLIC_URL/api/health" 2>/dev/null || true)"- gateway_health_body_ok "$body" "${RUNTIME_INSTANCE_ID:-}" && return 0+ gateway_health_body_matches_identity "$body" "$LOCAL_HEALTH_IDENTITY" && return 0done < <(gateway_quick_public_ipv4s || true)return 1}@@ -141,7 +141,7 @@ gateway_probe_public() {# propagated. Do not weaken the MSO health/instance check; give the provider a# bounded readiness window instead. Named tunnels usually pass on the first poll.for i in $(seq 1 "$seconds"); do- gateway_health_url_ok "$GATEWAY_PUBLIC_URL" "${RUNTIME_INSTANCE_ID:-}" && return 0+ gateway_health_url_matches_identity "$GATEWAY_PUBLIC_URL" "$LOCAL_HEALTH_IDENTITY" && return 0gateway_quick_edge_health_ok && return 0sleep 1done@@ -151,7 +151,8 @@ gateway_probe_public() {gateway_cleanup_failed_start() {if [ "${TUNNEL_IDENTITY:-null}" != null ]; then gateway_stop_identity "$TUNNEL_IDENTITY"else gateway_stop_pending_tunnel; fi- [ "${RUNTIME_STARTED_NOW:-false}" != true ] || gateway_stop_identity "$RUNTIME_IDENTITY"+ if [ "${RUNTIME_STARTED_NOW:-false}" = true ]; then gateway_stop_identity "$RUNTIME_IDENTITY"+ else gateway_stop_pending_runtime; fi}gateway_cmd_start_locked() {@@ -166,6 +167,8 @@ gateway_cmd_start_locked() {gateway_runtime_from_state "$state"gateway_start_runtime_if_neededgateway_assert_port_loopback_only+ LOCAL_HEALTH_IDENTITY="$(gateway_health_url_identity "$LOCAL_URL" "${RUNTIME_INSTANCE_ID:-}")" \+ || { gateway_cleanup_failed_start; gateway_fail "selected local runtime did not return a stable MSO health identity"; }TUNNEL_IDENTITY=null; GATEWAY_PUBLIC_URL="${GATEWAY_PUBLIC_URL:-}"gateway_spawn_tunnel || { gateway_cleanup_failed_start; gateway_fail "cloudflared failed to start with the expected argv"; }if [ "$GATEWAY_MODE" = temporary ]; thendiff --git a/scripts/lib/update-state.sh b/scripts/lib/update-state.shindex 6aabfeef..d76d81ac 100755--- a/scripts/lib/update-state.sh+++ b/scripts/lib/update-state.sh@@ -7,6 +7,7 @@ DEPLOY_RECEIPT=''RESTART_MARKER=''UPDATE_LOCK_DIR=''UPDATE_LOCK_HELD=0+UPDATE_LOCK_FD=''update_proc_start_ticks() {local pid="$1" line rest@@ -63,37 +64,25 @@ clear_restart_pending() {mso_private_state_remove_file "$RESTART_MARKER" >/dev/null 2>&1 || true}-update_lock_owner_valid() {- local owner="$UPDATE_LOCK_DIR/owner" pid ticks live- [ -f "$owner" ] && [ ! -L "$owner" ] || return 1- read -r pid ticks <"$owner" || return 1- [[ "$pid" =~ ^[0-9]+$ && "$ticks" =~ ^[0-9]+$ ]] || return 1- live="$(update_proc_start_ticks "$pid" 2>/dev/null || true)"- [ -n "$live" ] && [ "$live" = "$ticks" ]-}-update_lock_acquire() {- local self_ticks candidate stale iinit_update_state- self_ticks="$(update_proc_start_ticks $$)" || fail "cannot identify update process"- for i in $(seq 1 1200); do- candidate="$UPDATE_STATE_DIR/.transaction-lock.$$.$RANDOM"- if ! mkdir -m 700 -- "$candidate" 2>/dev/null; then sleep 0.01; continue; fi- printf '%s %s\n' "$$" "$self_ticks" >"$candidate/owner"; chmod 600 "$candidate/owner"- if mv -T -- "$candidate" "$UPDATE_LOCK_DIR" 2>/dev/null; then UPDATE_LOCK_HELD=1; return 0; fi- rm -rf -- "$candidate"- if [ -d "$UPDATE_LOCK_DIR" ] && [ ! -L "$UPDATE_LOCK_DIR" ] && ! update_lock_owner_valid; then- stale="$UPDATE_STATE_DIR/.transaction-stale.$$.$RANDOM"- mv -T -- "$UPDATE_LOCK_DIR" "$stale" 2>/dev/null && rm -rf -- "$stale" || true- fi- sleep 0.05- done- fail "another offline update transaction is still running"+ mso_private_state_ensure_file "$UPDATE_LOCK_DIR" >/dev/null || fail "unsafe offline update transaction lock"+ exec {UPDATE_LOCK_FD}<>"$UPDATE_LOCK_DIR" || fail "cannot open offline update transaction lock"+ if ! flock -x -w 900 "$UPDATE_LOCK_FD"; then+ exec {UPDATE_LOCK_FD}>&- || true+ UPDATE_LOCK_FD=''+ fail "another offline update transaction is still running"+ fi+ UPDATE_LOCK_HELD=1}update_lock_release() {[ "$UPDATE_LOCK_HELD" = 1 ] || return 0- if update_lock_owner_valid; then rm -f -- "$UPDATE_LOCK_DIR/owner"; rmdir -- "$UPDATE_LOCK_DIR" 2>/dev/null || true; fi+ if [ -n "${UPDATE_LOCK_FD:-}" ]; then+ flock -u "$UPDATE_LOCK_FD" 2>/dev/null || true+ exec {UPDATE_LOCK_FD}>&- || true+ UPDATE_LOCK_FD=''+ fiUPDATE_LOCK_HELD=0}diff --git a/scripts/mso-gateway b/scripts/mso-gatewayindex da6afe5f..66107a06 100755--- a/scripts/mso-gateway+++ b/scripts/mso-gateway@@ -8,11 +8,14 @@ ROOT="${MSO_GATEWAY_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"ENVF="${MSO_GATEWAY_ENV:-$ROOT/.env.local}"LOCAL_URL_OVERRIDE="${MSO_GATEWAY_LOCAL_URL:-}"LOCAL_URL=""-STATE_ROOT="${MSO_GATEWAY_STATE_DIR:-$HOME/.mso/private/gateway}"+STATE_ROOT_OVERRIDE="${MSO_GATEWAY_STATE_DIR:-}"+STATE_ROOT=''+GATEWAY_CANONICAL_ROOT=''+GATEWAY_SCOPE_ID=''CLOUDFLARED=""CURL="${MSO_GATEWAY_CURL:-$(command -v curl 2>/dev/null || true)}"-for dep in node jq sha256sum realpath stat mktemp; do command -v "$dep" >/dev/null || { echo "mso gateway: missing dependency: $dep" >&2; exit 1; }; done+for dep in node jq sha256sum realpath stat mktemp flock; do command -v "$dep" >/dev/null || { echo "mso gateway: missing dependency: $dep" >&2; exit 1; }; done[ -n "$CURL" ] || { echo "mso gateway: curl is required" >&2; exit 1; }# shellcheck source=scripts/lib/private-state.sh@@ -34,12 +37,22 @@ fiLOCAL_URL="${LOCAL_URL_OVERRIDE:-${MSO_GATEWAY_LOCAL_URL:-http://127.0.0.1:${MSO_PORT:-4005}}}"LOCAL_URL="$(gateway_validate_loopback_origin "$LOCAL_URL" 2>/dev/null || true)"[ -n "$LOCAL_URL" ] || gateway_fail "refusing non-loopback/invalid upstream; use a clean http://127/8, localhost, or ::1 origin with an explicit port"-STATE_ROOT="$(mso_private_state_dir "$STATE_ROOT")" || gateway_fail "unsafe gateway state directory"+GATEWAY_CANONICAL_ROOT="$(realpath -e -- "$ROOT" 2>/dev/null || true)"+[ -n "$GATEWAY_CANONICAL_ROOT" ] || gateway_fail "cannot canonicalize MSO checkout: $ROOT"+GATEWAY_SCOPE_ID="$(printf '%s\n%s' "$GATEWAY_CANONICAL_ROOT" "$LOCAL_URL" | sha256sum | awk '{print $1}')"+[[ "$GATEWAY_SCOPE_ID" =~ ^[0-9a-f]{64}$ ]] || gateway_fail "cannot derive gateway state scope"+if [ -n "$STATE_ROOT_OVERRIDE" ]; then+ STATE_ROOT="$(mso_private_state_dir "$STATE_ROOT_OVERRIDE")" || gateway_fail "unsafe gateway state directory"+else+ STATE_BASE="$(mso_private_state_dir "$HOME/.mso/private/gateway")" || gateway_fail "unsafe gateway state base"+ STATE_ROOT="$(mso_private_state_dir "$STATE_BASE/$GATEWAY_SCOPE_ID")" || gateway_fail "unsafe scoped gateway state directory"+fiSTATE_FILE="$STATE_ROOT/state.json"CF_LOG="$STATE_ROOT/cloudflared.log"RUNTIME_LOG="$STATE_ROOT/runtime.log"-LOCK_DIR="$STATE_ROOT/lifecycle.lock"+LOCK_FILE="$STATE_ROOT/lifecycle.lock"LOCK_HELD=0+GATEWAY_LOCK_FD=''# shellcheck source=scripts/lib/gateway-network.sh. "$ROOT/scripts/lib/gateway-network.sh"@@ -47,6 +60,8 @@ LOCK_HELD=0. "$ROOT/scripts/lib/gateway-tool.sh"# shellcheck source=scripts/lib/gateway-lock.sh. "$ROOT/scripts/lib/gateway-lock.sh"+# shellcheck source=scripts/lib/gateway-health.sh+. "$ROOT/scripts/lib/gateway-health.sh"# shellcheck source=scripts/lib/gateway-recovery.sh. "$ROOT/scripts/lib/gateway-recovery.sh"# shellcheck source=scripts/lib/gateway-runtime.shdiff --git a/scripts/mso-gateway-boundaries.test.ts b/scripts/mso-gateway-boundaries.test.tsnew file mode 100644index 00000000..01fae570--- /dev/null+++ b/scripts/mso-gateway-boundaries.test.ts@@ -0,0 +1,67 @@+import { execFileSync, spawnSync } from "node:child_process";+import fs from "node:fs";+import path from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import { GATEWAY, ROOT, VERSION, cleanupGatewayFixtures, fixture, runGateway as run } from "./mso-gateway-test-fixture";++afterEach(() => cleanupGatewayFixtures());++describe("mso gateway scope and public identity boundaries", () => {+ it("isolates default gateway state by checkout and selected loopback origin", () => {+ const f = fixture();+ const base: NodeJS.ProcessEnv = { ...f.baseEnv }; delete base.MSO_GATEWAY_STATE_DIR;+ const env4005 = { ...base, MSO_GATEWAY_LOCAL_URL: "http://127.0.0.1:4005" };+ const env4555 = { ...base, MSO_GATEWAY_LOCAL_URL: "http://127.0.0.1:4555" };+ const clone = path.join(f.dir, "clone-b");+ fs.mkdirSync(path.join(clone, "scripts"), { recursive: true });+ fs.cpSync(path.join(ROOT, "scripts/lib"), path.join(clone, "scripts/lib"), { recursive: true });+ fs.copyFileSync(GATEWAY, path.join(clone, "scripts/mso-gateway"));+ fs.chmodSync(path.join(clone, "scripts/mso-gateway"), 0o755);+ fs.copyFileSync(path.join(ROOT, "package.json"), path.join(clone, "package.json"));+ const envClone = { ...env4005, MSO_GATEWAY_ROOT: clone, MSO_GATEWAY_ARTIFACT_LOCK: path.join(ROOT, "security/gateway-artifacts.env") };+ try {+ run(["start"], env4005); run(["start"], env4555);+ execFileSync(path.join(clone, "scripts/mso-gateway"), ["start"], { encoding: "utf8", env: envClone });+ const stateBase = path.join(f.dir, ".mso/private/gateway");+ const states = fs.readdirSync(stateBase, { withFileTypes: true }).filter((e) => e.isDirectory())+ .map((e) => path.join(stateBase, e.name, "state.json")).filter(fs.existsSync);+ expect(states).toHaveLength(3);+ const scopes = states.map((file) => JSON.parse(fs.readFileSync(file, "utf8")) as { scopeId: string; localUrl: string; root: string });+ expect(new Set(scopes.map((v) => v.scopeId)).size).toBe(3);+ expect(new Set(scopes.map((v) => v.localUrl))).toEqual(new Set(["http://127.0.0.1:4005", "http://127.0.0.1:4555"]));+ expect(new Set(scopes.map((v) => v.root)).size).toBe(2);+ } finally {+ try { run(["stop"], env4005); } catch {}+ try { run(["stop"], env4555); } catch {}+ try { execFileSync(path.join(clone, "scripts/mso-gateway"), ["stop"], { env: envClone }); } catch {}+ }+ }, 20_000);++ it("rejects a public route whose health identity belongs to another MSO deployment", () => {+ const f = fixture();+ fs.writeFileSync(f.curl, `#!/bin/sh+case "$*" in+ *127.0.0.1:4005/api/health*) printf '%s\n' '{"status":"ok","buildId":"selected-build","runtimeInstanceId":null,"version":"${VERSION}"}' ;;+ *mso.example.test/api/health*) printf '%s\n' '{"status":"ok","buildId":"other-build","runtimeInstanceId":null,"version":"${VERSION}"}' ;;+ *) printf '%s\n' '{"status":"ok","buildId":"selected-build","runtimeInstanceId":null,"version":"${VERSION}"}' ;;+esac+`, { mode: 0o700 });+ const credentials = path.join(f.dir, "identity-tunnel.json"); fs.writeFileSync(credentials, "{}\n", { mode: 0o600 });+ const config = path.join(f.dir, "identity-tunnel.yml");+ fs.writeFileSync(config, `tunnel: fixture\ncredentials-file: ${credentials}\ningress:\n - hostname: mso.example.test\n service: http://127.0.0.1:4005\n - service: http_status:404\n`, { mode: 0o600 });+ const out = spawnSync(GATEWAY, ["start", "--config", config, "--tunnel", "fixture"], { encoding: "utf8",+ env: { ...f.baseEnv, OS_PUBLIC_ORIGIN: "https://mso.example.test", MSO_GATEWAY_SKIP_PUBLIC_PROBE: "0", MSO_GATEWAY_PUBLIC_READY_SECONDS: "10" } });+ expect(out.status).not.toBe(0);+ expect(out.stderr).toContain("public endpoint did not return the MSO health contract");+ expect(fs.existsSync(path.join(f.state, "state.json"))).toBe(false);+ }, 15_000);++ it("uses kernel flock locks instead of stale-directory reclamation", () => {+ for (const name of ["gateway-lock.sh", "update-state.sh"]) {+ const source = fs.readFileSync(path.join(ROOT, "scripts/lib", name), "utf8");+ expect(source).toContain("flock -x");+ expect(source).not.toContain("transaction-stale");+ expect(source).not.toContain("lifecycle-stale");+ }+ });+});diff --git a/scripts/mso-gateway-lifecycle.test.ts b/scripts/mso-gateway-lifecycle.test.tsindex c93153a8..5fa63794 100644--- a/scripts/mso-gateway-lifecycle.test.ts+++ b/scripts/mso-gateway-lifecycle.test.ts@@ -42,7 +42,12 @@ function identity(pid: number) {return { pid, startTicks: rest[19], exe: fs.realpathSync(`/proc/${pid}/exe`),cmdHash: createHash("sha256").update(fs.readFileSync(`/proc/${pid}/cmdline`)).digest("hex") };}-function writeState(dir: string, value: unknown) { fs.writeFileSync(path.join(dir, "state.json"), JSON.stringify(value), { mode: 0o600 }); }+function writeState(dir: string, value: Record<string, unknown>) {+ const localUrl = String(value.localUrl ?? "http://127.0.0.1:4005");+ const root = fs.realpathSync(ROOT);+ const scopeId = createHash("sha256").update(`${root}\n${localUrl}`).digest("hex");+ fs.writeFileSync(path.join(dir, "state.json"), JSON.stringify({ scopeId, root, ...value }), { mode: 0o600 });+}function readRegularSnapshot(file: string) {const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);try {diff --git a/scripts/mso-gateway-runtime-signal.test.ts b/scripts/mso-gateway-runtime-signal.test.tsnew file mode 100644index 00000000..be43bc6e--- /dev/null+++ b/scripts/mso-gateway-runtime-signal.test.ts@@ -0,0 +1,44 @@+import { spawn } from "node:child_process";+import fs from "node:fs";+import path from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import { GATEWAY, ROOT, VERSION, cleanupGatewayFixtures, fixture } from "./mso-gateway-test-fixture";++const pids = new Set<number>();+function alive(pid: number) { try { process.kill(pid, 0); return true; } catch { return false; } }+afterEach(() => {+ for (const pid of pids) if (alive(pid)) try { process.kill(pid, "SIGTERM"); } catch {}+ pids.clear(); cleanupGatewayFixtures();+});++describe("mso fallback runtime signal safety", () => {+ it("cleans a fallback runtime when the launcher is terminated before state persistence", async () => {+ const f = fixture(), root = path.join(f.dir, "runtime-root");+ fs.mkdirSync(path.join(root, "scripts"), { recursive: true });+ fs.cpSync(path.join(ROOT, "scripts/lib"), path.join(root, "scripts/lib"), { recursive: true });+ fs.copyFileSync(GATEWAY, path.join(root, "scripts/mso-gateway")); fs.chmodSync(path.join(root, "scripts/mso-gateway"), 0o755);+ fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ version: VERSION }));+ fs.mkdirSync(path.join(root, ".next"), { recursive: true }); fs.writeFileSync(path.join(root, ".next/BUILD_ID"), "fixture\n");+ fs.mkdirSync(path.join(root, "node_modules/next/dist/bin"), { recursive: true });+ const pidFile = path.join(f.dir, "runtime-pid");+ fs.writeFileSync(path.join(root, "node_modules/next/dist/bin/next"), `+const http=require('http'), fs=require('fs'); const args=process.argv.slice(2);+const port=Number(args[args.indexOf('--port')+1]); fs.writeFileSync(process.env.MSO_TEST_RUNTIME_PID_FILE, String(process.pid));+http.createServer((req,res)=>{res.setHeader('content-type','application/json');res.end(JSON.stringify({status:'ok',buildId:'fixture',runtimeInstanceId:process.env.MSO_RUNTIME_INSTANCE_ID,version:${JSON.stringify(VERSION)}}));}).listen(port,'127.0.0.1');+process.on('SIGTERM',()=>process.exit(0));+`);+ const port = 41000 + Math.floor(Math.random() * 10000), curl = path.join(f.dir, "bin", "curl-never-ready");+ fs.writeFileSync(curl, "#!/bin/sh\nexit 7\n", { mode: 0o700 });+ const state = path.join(f.dir, "runtime-state");+ const env = { ...f.baseEnv, MSO_GATEWAY_ROOT: root, MSO_GATEWAY_ARTIFACT_LOCK: path.join(ROOT, "security/gateway-artifacts.env"),+ MSO_GATEWAY_STATE_DIR: state, MSO_GATEWAY_LOCAL_URL: `http://127.0.0.1:${port}`, MSO_GATEWAY_CURL: curl, MSO_TEST_RUNTIME_PID_FILE: pidFile };+ const child = spawn(path.join(root, "scripts/mso-gateway"), ["local-start"], { env, stdio: ["ignore", "pipe", "pipe"] });+ for (let i = 0; i < 150 && !fs.existsSync(pidFile); i++) await new Promise((r) => setTimeout(r, 20));+ expect(fs.existsSync(pidFile)).toBe(true);+ const runtimePid = Number(fs.readFileSync(pidFile, "utf8")); pids.add(runtimePid);+ child.kill("SIGTERM"); await new Promise<void>((resolve) => child.once("close", () => resolve()));+ for (let i = 0; i < 100 && alive(runtimePid); i++) await new Promise((r) => setTimeout(r, 20));+ expect(alive(runtimePid)).toBe(false);+ expect(fs.existsSync(path.join(state, "state.json"))).toBe(false);+ }, 15_000);+});diff --git a/scripts/mso-gateway.test.ts b/scripts/mso-gateway.test.tsindex 955d31cf..5e91c99b 100644--- a/scripts/mso-gateway.test.ts+++ b/scripts/mso-gateway.test.ts@@ -3,7 +3,7 @@ import fs from "node:fs";import path from "node:path";import { afterEach, describe, expect, it } from "vitest";import {- CLI, GATEWAY, VERSION, cleanupGatewayFixtures, fixture, readFileSnapshot, readState, runGateway as run,+ CLI, GATEWAY, ROOT, VERSION, cleanupGatewayFixtures, fixture, readFileSnapshot, readState, runGateway as run,} from "./mso-gateway-test-fixture";afterEach(cleanupGatewayFixtures);