Skip to content

armgit / mso

Public Imported from GitHub
0

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.

fix(runtime): verify live update identities

Rahmane7acdafab5ff
diff --git a/app/api/health/route.test.ts b/app/api/health/route.test.ts
index fb19c173..c90b8d5e 100644
--- a/app/api/health/route.test.ts
+++ b/app/api/health/route.test.ts
@@ -15,13 +15,24 @@ describe("/api/health", () => {
expect(res.status).toBe(200);
const body = (await res.json()) as Record<string, unknown>;
expect(body.status).toBe("ok");
+ expect(body.service).toBe("mso");
expect(typeof body.buildId).toBe("string");
+ expect(body.buildSha === null || typeof body.buildSha === "string").toBe(true);
expect(typeof body.uptime).toBe("number");
expect((body.uptime as number) >= 0).toBe(true);
expect(typeof body.version).toBe("string");
expect((body.version as string).length).toBeGreaterThan(0);
});
+ it("returns the commit identity baked into the running build", async () => {
+ vi.stubEnv("NEXT_PUBLIC_COMMIT_SHA", "abc1234");
+ const { GET } = await import("./route");
+ const res = await GET();
+ const body = (await res.json()) as Record<string, unknown>;
+ expect(body.service).toBe("mso");
+ expect(body.buildSha).toBe("abc1234");
+ });
+
it("returns the runtime instance id supplied by the service manager", async () => {
vi.stubEnv("MSO_RUNTIME_INSTANCE_ID", "restart-proof-123");
const { GET } = await import("./route");
diff --git a/app/api/health/route.ts b/app/api/health/route.ts
index 88333c70..c884d5fe 100644
--- a/app/api/health/route.ts
+++ b/app/api/health/route.ts
@@ -12,7 +12,9 @@ export async function GET() {
return NextResponse.json(
{
status: "ok",
+ service: "mso",
buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",
+ buildSha: process.env.NEXT_PUBLIC_COMMIT_SHA || null,
runtimeInstanceId: process.env.MSO_RUNTIME_INSTANCE_ID || null,
version: pkg.version ?? "0.0.0",
demo: true,
@@ -24,7 +26,9 @@ export async function GET() {
return NextResponse.json(
{
status: "ok",
+ service: "mso",
buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",
+ buildSha: process.env.NEXT_PUBLIC_COMMIT_SHA || null,
runtimeInstanceId: process.env.MSO_RUNTIME_INSTANCE_ID || null,
uptime: Math.round(process.uptime()),
version: pkg.version ?? "0.0.0",
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index bf18938e..8e5fad9d 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**
+- `runtime` verify live update identities
- `runtime` close final update web edges
- `update` emit success after runtime restore
- `update` serialize all checkout runtimes
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 09b01625..362fee96 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -165,7 +165,7 @@ never changes the application bind to `0.0.0.0`. The tool cache is user-local an
with Cloudflare auto-update disabled. The tunnel process also receives a scrubbed environment rather
than inheriting MSO login/session/BYOK secrets from the application shell. If systemd is unavailable (common on WSL), it may start the
already-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 and scoped by the canonical checkout plus selected loopback
+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. After TERM/SIGKILL, MSO re-verifies that the exact recorded process identity disappeared before deleting lifecycle state; an unverified survivor leaves state intact and the stop fails closed. 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
@@ -284,7 +284,7 @@ when the application exists.
Production health is:
```text
-GET /api/health -> {status, buildId, uptime, version}
+GET /api/health -> {status, service, buildId, buildSha, runtimeInstanceId, uptime, version}
```
### Service Center policy
@@ -453,8 +453,11 @@ Git already reached `origin/main` is retried by the next ordinary `mso update` i
mislabeled "already up to date". The state is keyed by canonical checkout path, so two clones at the
same SHA cannot borrow each other's receipt. One owner-only transaction lock covers every service-active or offline in-place update, from source/receipt reconciliation through gateway runtime restore and receipt write. Recovery intent is written to private state
before a gateway-owned runtime is quiesced, so an interrupted post-quiesce state update stays retryable.
-Interactive CLI commands also show a throttled Git-backed update notice;
-the notice never depends on port 4005. A successful service finalizer log ends with `UPDATE OK`.
+Interactive CLI commands also show a throttled Git-backed source-update notice. When the system
+service is active and source is already current, the notice/status path performs a bounded loopback
+`/api/health` identity check and offers `mso update --rebuild` if the running build SHA differs or
+cannot be proven. The offline updater itself remains API-independent. A successful service finalizer
+log ends with `UPDATE OK`.
If the installed source is correct but the production build tree is inconsistent, use:
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 1b999fed..d274dbbf 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -38,6 +38,8 @@ when Git HEAD already equals `origin/main`. Offline transactions are serialized;
owner-only update-state directory just to bypass a pending recovery. Recovery intent is written before
a gateway-owned runtime is quiesced, so an interrupted state update remains safely retryable. Use
`mso update status` for source/deployment state and `mso update log` for the service-updater transcript.
+When `mso.service` is active, status also compares the commit baked into the live loopback `/api/health`
+response with source `HEAD`; source equality alone is not treated as proof that deployment finished.
### `mso update` says the active service belongs to another checkout
diff --git a/scripts/gateway-stop-identity.test.ts b/scripts/gateway-stop-identity.test.ts
new file mode 100644
index 00000000..1769cb41
--- /dev/null
+++ b/scripts/gateway-stop-identity.test.ts
@@ -0,0 +1,35 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const COMMON = path.join(process.cwd(), "scripts/lib/gateway-common.sh");
+
+function run(body: string) {
+ return spawnSync("bash", ["-c", `set -euo pipefail
+source ${JSON.stringify(COMMON)}
+${body}`], { encoding: "utf8" });
+}
+
+describe("gateway_stop_identity", () => {
+ it("fails closed when the same process identity survives SIGKILL", () => {
+ const result = run(`
+gateway_identity_matches() { return 0; }
+kill() { return 0; }
+sleep() { :; }
+gateway_stop_identity '{"pid":4242}'
+`);
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain("survived SIGKILL; preserving lifecycle state");
+ });
+
+ it("succeeds once the recorded identity disappears", () => {
+ const result = run(`
+checks=0
+gateway_identity_matches() { checks=$((checks+1)); [ "$checks" -lt 3 ]; }
+kill() { return 0; }
+sleep() { :; }
+gateway_stop_identity '{"pid":4242}'
+`);
+ expect(result.status).toBe(0);
+ });
+});
diff --git a/scripts/lib/gateway-common.sh b/scripts/lib/gateway-common.sh
index fc7910d5..d17150c1 100644
--- a/scripts/lib/gateway-common.sh
+++ b/scripts/lib/gateway-common.sh
@@ -155,5 +155,16 @@ gateway_stop_identity() {
gateway_identity_matches "$identity" || return 0
sleep 0.1
done
- gateway_identity_matches "$identity" && kill -KILL "$pid" 2>/dev/null || true
+ if gateway_identity_matches "$identity"; then
+ kill -KILL "$pid" 2>/dev/null || true
+ for i in $(seq 1 20); do
+ gateway_identity_matches "$identity" || return 0
+ sleep 0.05
+ done
+ fi
+ if gateway_identity_matches "$identity"; then
+ printf 'mso gateway: process %s survived SIGKILL; preserving lifecycle state\n' "$pid" >&2
+ return 1
+ fi
+ return 0
}
diff --git a/scripts/lib/gateway-runtime.sh b/scripts/lib/gateway-runtime.sh
index 142e9e06..db4522b0 100644
--- a/scripts/lib/gateway-runtime.sh
+++ b/scripts/lib/gateway-runtime.sh
@@ -165,8 +165,12 @@ gateway_cmd_stop_locked() {
tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"
runtime="$(jq -c '.runtimeIdentity // null' <<<"$state")"
owned="$(jq -r '.runtimeOwned // false' <<<"$state")"
- [ "$tunnel" = null ] || gateway_stop_identity "$tunnel"
- [ "$owned" != true ] || [ "$runtime" = null ] || gateway_stop_identity "$runtime"
+ if [ "$tunnel" != null ]; then
+ gateway_stop_identity "$tunnel" || gateway_fail "tunnel process could not be proven stopped; lifecycle state was preserved"
+ fi
+ if [ "$owned" = true ] && [ "$runtime" != null ]; then
+ gateway_stop_identity "$runtime" || gateway_fail "runtime process could not be proven stopped; lifecycle state was preserved"
+ fi
mso_private_state_remove_file "$STATE_FILE" >/dev/null 2>&1 || true
gateway_info "gateway stopped; MSO remains loopback-only"
}
diff --git a/scripts/mso-update b/scripts/mso-update
index 177a1363..8ce9dfc7 100755
--- a/scripts/mso-update
+++ b/scripts/mso-update
@@ -33,6 +33,26 @@ fetch_main() { git -C "$ROOT" fetch --quiet origin main || fail "could not reach
service_is_active() { command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet mso.service; }
+service_port() {
+ local raw port
+ raw="$(systemctl show -p Environment --value mso.service 2>/dev/null || true)"
+ port="$(printf '%s\n' "$raw" | tr ' ' '\n' | sed -n 's/^PORT=//p' | head -1)"
+ if ! [[ "$port" =~ ^[0-9]+$ ]] || [ "$port" -lt 1 ] || [ "$port" -gt 65535 ]; then port=4005; fi
+ printf '%s' "$port"
+}
+
+service_build_sha() {
+ local timeout="${1:-3}" port body sha
+ port="$(service_port)"
+ body="$(curl --noproxy '*' -fsS --connect-timeout "$timeout" --max-time "$timeout" "http://127.0.0.1:$port/api/health" 2>/dev/null)" || return 1
+ sha="$(printf '%s' "$body" | jq -er '
+ select(.status == "ok" and .service == "mso")
+ | .buildSha
+ | select(type == "string" and test("^[0-9a-f]{7,40}$"))
+ ' 2>/dev/null)" || return 1
+ printf '%s' "$sha"
+}
+
require_service_checkout() {
local configured canonical_root canonical_service
configured="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"
@@ -59,8 +79,17 @@ print_status() {
return
fi
if service_is_active; then
+ local running_sha head_short
require_service_checkout
- printf 'mso %s is up to date (%s)\n' "${local_v:-unknown}" "${head:0:7}"
+ head_short="$(git -C "$ROOT" rev-parse --short HEAD)"
+ running_sha="$(service_build_sha 2>/dev/null || true)"
+ if [ -z "$running_sha" ]; then
+ printf 'source is current at %s, but the active service build identity is unavailable. deployment verification/rebuild is pending. run: mso update --rebuild\n' "$head_short"
+ elif [[ "$head" != "$running_sha"* ]]; then
+ printf 'source is current at %s, but mso.service is still running %s. deployment verification/rebuild is pending. run: mso update --rebuild\n' "$head_short" "$running_sha"
+ else
+ printf 'mso %s is up to date (%s)\n' "${local_v:-unknown}" "$head_short"
+ fi
return
fi
init_update_state
@@ -82,9 +111,28 @@ notice() {
printf '%s\n' "$now" | mso_private_state_atomic_write "$stamp" >/dev/null 2>&1 || true
(cd "$ROOT" && nohup git fetch --quiet origin main >/dev/null 2>&1 </dev/null &) || true
fi
- n="$(behind)"; [ "$n" -gt 0 ] || return 0; local_v="$(current_version)"; remote_v="$(remote_version)"
- printf 'MSO update available: %s -> %s (%s commit%s). Run: mso update\n' \
- "${local_v:-current}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)" >&2
+ n="$(behind)"
+ if [ "$n" -gt 0 ]; then
+ local_v="$(current_version)"; remote_v="$(remote_version)"
+ printf 'MSO update available: %s -> %s (%s commit%s). Run: mso update\n' \
+ "${local_v:-current}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)" >&2
+ return 0
+ fi
+ if service_is_active; then
+ local running_sha head_short head_full configured canonical_root canonical_service
+ configured="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"
+ canonical_root="$(realpath -e -- "$ROOT" 2>/dev/null || true)"
+ canonical_service="$(realpath -e -- "$configured" 2>/dev/null || true)"
+ if [ -n "$canonical_root" ] && [ "$canonical_service" = "$canonical_root" ]; then
+ head_short="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || true)"
+ head_full="$(git -C "$ROOT" rev-parse HEAD 2>/dev/null || true)"
+ running_sha="$(service_build_sha 0.5 2>/dev/null || true)"
+ if [ -n "$head_short" ] && { [ -z "$running_sha" ] || [[ "$head_full" != "$running_sha"* ]]; }; then
+ printf 'MSO deployment rebuild pending: source %s, running %s. Run: mso update --rebuild\n' \
+ "$head_short" "${running_sha:-unknown}" >&2
+ fi
+ fi
+ fi
}
offline_build_locked() {
diff --git a/scripts/mso-update-service-status.test.ts b/scripts/mso-update-service-status.test.ts
new file mode 100644
index 00000000..202c2d07
--- /dev/null
+++ b/scripts/mso-update-service-status.test.ts
@@ -0,0 +1,81 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const SCRIPT = path.join(process.cwd(), "scripts/mso-update");
+const LIBS = ["private-state.sh", "update-state.sh", "runtime-exclusion.sh", "update-gateway-runtimes.sh"];
+const roots: string[] = [];
+
+function git(cwd: string, ...args: string[]) {
+ return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+
+function fixture() {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "mso-update-service-status-")); roots.push(root);
+ const repo = path.join(root, "repo"), remote = path.join(root, "remote.git"), bin = path.join(root, "bin");
+ fs.mkdirSync(path.join(repo, "scripts/lib"), { recursive: true }); fs.mkdirSync(path.join(repo, "bin")); fs.mkdirSync(bin);
+ for (const lib of LIBS) fs.copyFileSync(path.join(process.cwd(), "scripts/lib", lib), path.join(repo, "scripts/lib", lib));
+ fs.writeFileSync(path.join(repo, "bin/mso"), '#!/bin/sh\nVERSION="1.3.0"\n', { mode: 0o755 });
+ fs.writeFileSync(path.join(repo, "scripts/mso-gateway"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+ git(repo, "init", "-q", "-b", "main"); git(repo, "config", "user.name", "MSO Test"); git(repo, "config", "user.email", "[email protected]");
+ git(repo, "add", "."); git(repo, "commit", "-q", "-m", "old build"); const old = git(repo, "rev-parse", "HEAD");
+ git(root, "init", "--bare", "-q", remote); git(repo, "remote", "add", "origin", remote); git(repo, "push", "-q", "-u", "origin", "main");
+ fs.writeFileSync(path.join(repo, "bin/mso"), '#!/bin/sh\nVERSION="1.4.0"\n', { mode: 0o755 });
+ git(repo, "add", "bin/mso"); git(repo, "commit", "-q", "-m", "new build"); const current = git(repo, "rev-parse", "HEAD"); git(repo, "push", "-q", "origin", "main");
+ fs.writeFileSync(path.join(bin, "systemctl"), `#!/bin/sh
+if [ "$1" = is-active ]; then exit 0; fi
+if [ "$1" = show ]; then
+ case "$3" in
+ WorkingDirectory) printf '%s\n' ${JSON.stringify(repo)} ;;
+ Environment) printf '%s\n' 'PORT=4555' ;;
+ esac
+ exit 0
+fi
+exit 3
+`, { mode: 0o755 });
+ fs.writeFileSync(path.join(bin, "curl"), `#!/bin/sh
+case "$*" in
+ *127.0.0.1:4555/api/health*) printf '{"status":"ok","service":"mso","buildSha":"%s"}\n' "\${MSO_TEST_BUILD_SHA:-}" ;;
+ *) exit 97 ;;
+esac
+`, { mode: 0o755 });
+ const env = { ...process.env, HOME: path.join(root, "home"), PATH: `${bin}:${process.env.PATH}`, MSO_UPDATE_ROOT: repo,
+ MSO_UPDATE_STATE_DIR: path.join(root, "update-state"), MSO_UPDATE_NOTICE_DIR: path.join(root, "notice") };
+ return { repo, old, current, env };
+}
+
+afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); });
+
+describe("mso update active-service build identity", () => {
+ it("reports pending rebuild when source is current but the service runs an older build", () => {
+ const f = fixture(); const oldShort = git(f.repo, "rev-parse", "--short", f.old);
+ const out = execFileSync(SCRIPT, ["status"], { env: { ...f.env, MSO_TEST_BUILD_SHA: oldShort }, encoding: "utf8" });
+ expect(out).toContain("deployment verification/rebuild is pending");
+ expect(out).toContain(`still running ${oldShort}`);
+ expect(out).not.toContain("is up to date");
+ });
+
+ it("reports up to date only when the active service build matches source HEAD", () => {
+ const f = fixture(); const currentShort = git(f.repo, "rev-parse", "--short", f.current);
+ const out = execFileSync(SCRIPT, ["status"], { env: { ...f.env, MSO_TEST_BUILD_SHA: currentShort }, encoding: "utf8" });
+ expect(out).toContain(`is up to date (${currentShort})`);
+ expect(out).not.toContain("deployment verification/rebuild is pending");
+ });
+
+ it("fails safe when an active service cannot prove its running build identity", () => {
+ const f = fixture(); const out = execFileSync(SCRIPT, ["status"], { env: f.env, encoding: "utf8" });
+ expect(out).toContain("active service build identity is unavailable");
+ expect(out).toContain("deployment verification/rebuild is pending");
+ expect(out).not.toContain("is up to date");
+ });
+
+ it("prints an interactive rebuild notice when the running service build is stale", () => {
+ const f = fixture(); const oldShort = git(f.repo, "rev-parse", "--short", f.old);
+ const out = spawnSync(SCRIPT, ["notice"], { env: { ...f.env, MSO_TEST_BUILD_SHA: oldShort }, encoding: "utf8" });
+ expect(out.status).toBe(0); expect(out.stdout).toBe("");
+ expect(out.stderr).toContain(`source ${git(f.repo, "rev-parse", "--short", f.current)}, running ${oldShort}`);
+ expect(out.stderr).toContain("mso update --rebuild");
+ });
+});