@openparachute/hub 0.7.4-rc.8 → 0.7.4

package/src/__tests__/api-account-2fa.test.ts

@@ -0,0 +1,453 @@
+/**
+ * `/api/account/*` JSON self-service endpoints (hub#85): password change +
+ * 2FA start/confirm/disable. Plus `/api/me`'s `two_factor_enabled` field.
+ *
+ * Coverage:
+ *   - auth: no session → 401; wrong CSRF → 403; self-only (keyed off session)
+ *   - password: happy path (hash rotated + tokens revoked); wrong current →
+ *     401; too short → 400; mismatch handled client-side (not here); new ===
+ *     current → 400; too long → 413
+ *   - 2fa start → secret + qr; already-enrolled → 409
+ *   - 2fa confirm: round-trip with a live code persists + returns backup codes;
+ *     bad code → 400; malformed secret → 400
+ *   - 2fa disable: password-gated (wrong → 401), clears enrollment; idempotent
+ *   - /api/me reflects two_factor_enabled
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as OTPAuth from "otpauth";
+import { handleApiAccount } from "../api-account-2fa.ts";
+import { handleApiMe } from "../api-me.ts";
+import { CSRF_COOKIE_NAME } from "../csrf.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { recordTokenMint } from "../jwt-sign.ts";
+import { __resetForTests as resetRateLimit } from "../rate-limit.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession } from "../sessions.ts";
+import { _resetTotpReplayCache, generateTotpSecret } from "../totp.ts";
+import { isTotpEnrolled, persistEnrollment } from "../two-factor-store.ts";
+import { createUser, verifyPassword } from "../users.ts";
+
+const TEST_CSRF = "csrf-account-2fa-token";
+const CSRF_COOKIE = `${CSRF_COOKIE_NAME}=${TEST_CSRF}`;
+
+interface Harness {
+  db: Database;
+  configDir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const configDir = mkdtempSync(join(tmpdir(), "phub-api-account-2fa-"));
+  const db = openHubDb(hubDbPath(configDir));
+  return {
+    db,
+    configDir,
+    cleanup: () => {
+      db.close();
+      rmSync(configDir, { recursive: true, force: true });
+    },
+  };
+}
+
+async function userWithSession(
+  db: Database,
+  username: string,
+  password: string,
+): Promise<{ userId: string; cookie: string }> {
+  const user = await createUser(db, username, password, { passwordChanged: true });
+  const session = createSession(db, { userId: user.id });
+  const cookie = `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`;
+  return { userId: user.id, cookie };
+}
+
+function post(
+  subpath: string,
+  cookie: string | null,
+  body: Record<string, unknown>,
+): Promise<Response> {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (cookie) headers.cookie = cookie;
+  return handleApiAccount(
+    new Request(`http://hub.test/api/account${subpath}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    }),
+    subpath,
+    { db: harness.db },
+  );
+}
+
+function liveCode(secretBase32: string, label = "owner"): string {
+  return new OTPAuth.TOTP({
+    issuer: "Parachute Hub",
+    label,
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secretBase32),
+  }).generate();
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+  resetRateLimit();
+  _resetTotpReplayCache();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+describe("/api/account/* — auth posture", () => {
+  test("no session → 401", async () => {
+    const res = await post("/password", null, {
+      __csrf: TEST_CSRF,
+      current_password: "x",
+      new_password: "y",
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("wrong CSRF → 403", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, {
+      __csrf: "not-the-token",
+      current_password: "owner-password-123",
+      new_password: "brand-new-passphrase",
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("unknown subpath → 404", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/bogus", cookie, { __csrf: TEST_CSRF });
+    expect(res.status).toBe(404);
+  });
+
+  test("GET → 405", async () => {
+    const res = await handleApiAccount(
+      new Request("http://hub.test/api/account/password", { method: "GET" }),
+      "/password",
+      { db: harness.db },
+    );
+    expect(res.status).toBe(405);
+  });
+});
+
+describe("/api/account/password", () => {
+  test("happy path rotates the hash + revokes active tokens", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    // Seed an active token for this user — it should be revoked.
+    recordTokenMint(harness.db, {
+      jti: "tok-1",
+      userId,
+      subject: userId,
+      clientId: "cli",
+      scopes: ["vault:default:read"],
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      createdVia: "cli_mint",
+    });
+
+    const res = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "owner-password-123",
+      new_password: "brand-new-passphrase",
+    });
+    expect(res.status).toBe(200);
+
+    // New password verifies; old does not.
+    const row = harness.db
+      .query<{ password_hash: string }, [string]>("SELECT password_hash FROM users WHERE id = ?")
+      .get(userId);
+    expect(row).not.toBeNull();
+    const fakeUser = { passwordHash: row!.password_hash } as Parameters<typeof verifyPassword>[0];
+    expect(await verifyPassword(fakeUser, "brand-new-passphrase")).toBe(true);
+    expect(await verifyPassword(fakeUser, "owner-password-123")).toBe(false);
+
+    // Token revoked.
+    const tok = harness.db
+      .query<{ revoked_at: string | null }, [string]>("SELECT revoked_at FROM tokens WHERE jti = ?")
+      .get("tok-1");
+    expect(tok?.revoked_at).not.toBeNull();
+  });
+
+  test("wrong current password → 401 invalid_credentials", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "WRONG",
+      new_password: "brand-new-passphrase",
+    });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid_credentials");
+  });
+
+  test("new password too short → 400 invalid_password", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "owner-password-123",
+      new_password: "short",
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid_password");
+  });
+
+  test("new === current → 400 password_unchanged", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "owner-password-123",
+      new_password: "owner-password-123",
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("password_unchanged");
+  });
+
+  test("missing fields → 400", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, { __csrf: TEST_CSRF });
+    expect(res.status).toBe(400);
+  });
+
+  test("new password over PASSWORD_MAX_LEN → 413 (before argon2id hash)", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "owner-password-123",
+      new_password: "x".repeat(257),
+    });
+    expect(res.status).toBe(413);
+  });
+
+  test("rate-limited after repeated wrong-current attempts → 429", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    // Bucket is 3 attempts / 5 min (CHANGE_PASSWORD_*). Burn 3 wrong-current
+    // attempts (each 401), then the 4th is rejected at 429 BEFORE the verify.
+    for (let i = 0; i < 3; i++) {
+      const r = await post("/password", cookie, {
+        __csrf: TEST_CSRF,
+        current_password: "WRONG",
+        new_password: "brand-new-passphrase",
+      });
+      expect(r.status).toBe(401);
+    }
+    const limited = await post("/password", cookie, {
+      __csrf: TEST_CSRF,
+      current_password: "WRONG",
+      new_password: "brand-new-passphrase",
+    });
+    expect(limited.status).toBe(429);
+    expect(limited.headers.get("retry-after")).not.toBeNull();
+  });
+});
+
+describe("/api/account/2fa start + confirm", () => {
+  test("start returns a secret + otpauth_url + qr_data_url", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      secret: string;
+      otpauth_url: string;
+      qr_data_url: string;
+    };
+    expect(body.secret).toMatch(/^[A-Z2-7]+$/);
+    expect(body.otpauth_url.startsWith("otpauth://totp/")).toBe(true);
+    expect(body.qr_data_url.startsWith("data:image/png;base64,")).toBe(true);
+  });
+
+  test("start refuses (409) when already enrolled", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    await persistEnrollment(harness.db, userId, generateTotpSecret("owner").secret);
+    const res = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    expect(res.status).toBe(409);
+  });
+
+  test("confirm with a live code persists enrollment + returns backup codes", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const startRes = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    const { secret } = (await startRes.json()) as { secret: string };
+
+    const confirmRes = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret,
+      code: liveCode(secret),
+    });
+    expect(confirmRes.status).toBe(200);
+    const body = (await confirmRes.json()) as { enrolled: boolean; backup_codes: string[] };
+    expect(body.enrolled).toBe(true);
+    expect(body.backup_codes.length).toBe(10);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(true);
+  });
+
+  test("confirm with a wrong code → 400 invalid_code (not persisted)", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const startRes = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    const { secret } = (await startRes.json()) as { secret: string };
+    const res = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret,
+      code: "000000",
+    });
+    expect(res.status).toBe(400);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(false);
+  });
+
+  test("confirm with a malformed secret → 400 setup_expired", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret: "not-base32!!",
+      code: "123456",
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("setup_expired");
+  });
+
+  test("confirm is rate-limited after 10 attempts → 429 (lenient, #712)", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const startRes = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    const { secret } = (await startRes.json()) as { secret: string };
+    // 10 honest mistypes are admitted (each 400 invalid_code) — the lenient
+    // bucket doesn't punish a fumbling enroller.
+    for (let i = 0; i < 10; i++) {
+      const r = await post("/2fa/confirm", cookie, {
+        __csrf: TEST_CSRF,
+        secret,
+        code: "000000",
+      });
+      expect(r.status).toBe(400);
+    }
+    // 11th is denied by the limiter BEFORE the code is checked.
+    const denied = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret,
+      code: "000000",
+    });
+    expect(denied.status).toBe(429);
+    const body = (await denied.json()) as { error: string };
+    expect(body.error).toBe("too_many_attempts");
+    expect(denied.headers.get("retry-after")).toBeTruthy();
+    // The grind never touched enrollment.
+    expect(isTotpEnrolled(harness.db, userId)).toBe(false);
+  });
+
+  test("malformed-secret POSTs don't burn the confirm budget (#712)", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const startRes = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    const { secret } = (await startRes.json()) as { secret: string };
+    // 10 junk POSTs are rejected by the format guard BEFORE the limiter runs.
+    for (let i = 0; i < 10; i++) {
+      const r = await post("/2fa/confirm", cookie, {
+        __csrf: TEST_CSRF,
+        secret: "not-base32!!",
+        code: "000000",
+      });
+      expect(r.status).toBe(400);
+    }
+    // Budget untouched — the legit live code still enrolls on the next attempt.
+    const ok = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret,
+      code: liveCode(secret),
+    });
+    expect(ok.status).toBe(200);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(true);
+  });
+
+  test("a few mistypes then the live code within budget still enrolls (lenient)", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const startRes = await post("/2fa/start", cookie, { __csrf: TEST_CSRF });
+    const { secret } = (await startRes.json()) as { secret: string };
+    for (let i = 0; i < 3; i++) {
+      const r = await post("/2fa/confirm", cookie, {
+        __csrf: TEST_CSRF,
+        secret,
+        code: "000000",
+      });
+      expect(r.status).toBe(400);
+    }
+    const ok = await post("/2fa/confirm", cookie, {
+      __csrf: TEST_CSRF,
+      secret,
+      code: liveCode(secret),
+    });
+    expect(ok.status).toBe(200);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(true);
+  });
+});
+
+describe("/api/account/2fa/disable", () => {
+  test("password-gated: wrong password → 401, enrollment intact", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    await persistEnrollment(harness.db, userId, generateTotpSecret("owner").secret);
+    const res = await post("/2fa/disable", cookie, {
+      __csrf: TEST_CSRF,
+      password: "WRONG",
+    });
+    expect(res.status).toBe(401);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(true);
+  });
+
+  test("correct password clears enrollment", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    await persistEnrollment(harness.db, userId, generateTotpSecret("owner").secret);
+    const res = await post("/2fa/disable", cookie, {
+      __csrf: TEST_CSRF,
+      password: "owner-password-123",
+    });
+    expect(res.status).toBe(200);
+    expect(isTotpEnrolled(harness.db, userId)).toBe(false);
+  });
+
+  test("idempotent when already off", async () => {
+    const { cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    const res = await post("/2fa/disable", cookie, {
+      __csrf: TEST_CSRF,
+      password: "owner-password-123",
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("missing password → 400", async () => {
+    const { userId, cookie } = await userWithSession(harness.db, "owner", "owner-password-123");
+    await persistEnrollment(harness.db, userId, generateTotpSecret("owner").secret);
+    const res = await post("/2fa/disable", cookie, { __csrf: TEST_CSRF });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("/api/me — two_factor_enabled", () => {
+  test("false when not enrolled, true after enrollment", async () => {
+    const user = await createUser(harness.db, "owner", "owner-password-123", {
+      passwordChanged: true,
+    });
+    const session = createSession(harness.db, { userId: user.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+
+    const before = await handleApiMe(
+      new Request("http://hub.test/api/me", { headers: { cookie } }),
+      { db: harness.db },
+    );
+    const beforeBody = (await before.json()) as { two_factor_enabled?: boolean };
+    expect(beforeBody.two_factor_enabled).toBe(false);
+
+    await persistEnrollment(harness.db, user.id, generateTotpSecret("owner").secret);
+
+    const after = await handleApiMe(
+      new Request("http://hub.test/api/me", { headers: { cookie } }),
+      { db: harness.db },
+    );
+    const afterBody = (await after.json()) as { two_factor_enabled?: boolean };
+    expect(afterBody.two_factor_enabled).toBe(true);
+  });
+});

package/src/__tests__/api-mint-token.test.ts

@@ -172,6 +172,81 @@ describe("POST /api/auth/mint-token (hub#212 Phase 1)", () => {
     }
   });
 
+  // hub#516 parity — the live "mint refused" after `parachute hub set-origin`.
+  // An operator/agent credential minted under a PRIOR origin (still a member of
+  // the hub's bound-origin set) must keep minting after the canonical issuer
+  // switches; the minted token still carries the new canonical issuer.
+  describe("multi-origin issuer set (set-origin parity)", () => {
+    const TUNNEL = "https://brain.gitcoin.co";
+
+    test("mints when the bearer's iss is in knownIssuers but ≠ the canonical issuer", async () => {
+      const h = makeHarness();
+      try {
+        const { db, userId } = await bootstrap(h.dir);
+        try {
+          // Operator token minted under the TUNNEL origin (pre-`set-origin`).
+          const op = await mintOperatorToken(db, userId, { issuer: TUNNEL });
+          const resp = await handleApiMintToken(
+            jsonRequest(
+              { scope: "scribe:transcribe", expires_in: 3600 },
+              { authorization: `Bearer ${op.token}` },
+            ),
+            // Canonical issuer is now ISSUER (loopback), but the bound set still
+            // includes TUNNEL — the still-valid prior origin.
+            { db, issuer: ISSUER, knownIssuers: [ISSUER, TUNNEL] },
+          );
+          expect(resp.status).toBe(200);
+          const body = (await resp.json()) as { token: string };
+          // The MINTED token carries the canonical issuer, not the bearer's.
+          const validated = await validateAccessToken(db, body.token, ISSUER);
+          expect(validated.payload.iss).toBe(ISSUER);
+        } finally {
+          db.close();
+        }
+      } finally {
+        h.cleanup();
+      }
+    });
+
+    test("rejects 401 when the bearer's iss is OUTSIDE knownIssuers", async () => {
+      const h = makeHarness();
+      try {
+        const { db, userId } = await bootstrap(h.dir);
+        try {
+          const op = await mintOperatorToken(db, userId, { issuer: "https://evil.example.com" });
+          const resp = await handleApiMintToken(
+            jsonRequest({ scope: "scribe:transcribe" }, { authorization: `Bearer ${op.token}` }),
+            { db, issuer: ISSUER, knownIssuers: [ISSUER, TUNNEL] },
+          );
+          expect(resp.status).toBe(401);
+        } finally {
+          db.close();
+        }
+      } finally {
+        h.cleanup();
+      }
+    });
+
+    test("back-compat: without knownIssuers, a non-canonical iss is still rejected", async () => {
+      const h = makeHarness();
+      try {
+        const { db, userId } = await bootstrap(h.dir);
+        try {
+          const op = await mintOperatorToken(db, userId, { issuer: TUNNEL });
+          const resp = await handleApiMintToken(
+            jsonRequest({ scope: "scribe:transcribe" }, { authorization: `Bearer ${op.token}` }),
+            { db, issuer: ISSUER }, // no knownIssuers → falls back to [ISSUER]
+          );
+          expect(resp.status).toBe(401);
+        } finally {
+          db.close();
+        }
+      } finally {
+        h.cleanup();
+      }
+    });
+  });
+
   test("happy path: --scope-set=auth narrow operator token also passes the scope gate", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/api-modules.test.ts

@@ -6,8 +6,10 @@ import {
   API_MODULES_CHANNEL_REQUIRED_SCOPE,
   API_MODULES_REQUIRED_SCOPE,
   _clearLatestVersionCacheForTests,
+  defaultReadInstalledVersion,
   handleApiModules,
   handleApiModulesChannel,
+  isUpgradeAvailable,
 } from "../api-modules.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { getSetting, setModuleInstallChannel } from "../hub-settings.ts";
@@ -491,6 +493,147 @@ describe("GET /api/modules", () => {
     expect(scribe?.installed_version).toBeNull();
   });
 
+  // ── hub#243: upgrade-offer must be semver-aware + installed-version must be live ──
+
+  type UpgradeWire = {
+    short: string;
+    installed_version: string | null;
+    latest_version: string | null;
+    upgrade_available: boolean;
+  };
+
+  async function modulesWith(opts: {
+    installedVersion: string;
+    latest: string | null;
+    readInstalledVersion?: (installDir: string) => string | null;
+  }): Promise<UpgradeWire[]> {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: opts.installedVersion,
+        installDir: "/install/dir/vault",
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => opts.latest,
+      // Default: no live read (synthetic install dir has no package.json), so
+      // the services.json cache is used — matching the prior behavior.
+      readInstalledVersion: opts.readInstalledVersion ?? (() => null),
+    });
+    const body = (await res.json()) as { modules: UpgradeWire[] };
+    return body.modules;
+  }
+
+  test("does NOT offer an upgrade when the channel target is OLDER than installed (the live downgrade bug)", async () => {
+    // The exact live shape: rc operator installed 0.6.4-rc.15; channel resolved
+    // latest_version to the OLDER @latest 0.6.3. Strings differ, but it's a
+    // downgrade — upgrade_available MUST be false.
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.3" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    expect(vault?.latest_version).toBe("0.6.3");
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("offers an upgrade for a real rc → newer-rc move", async () => {
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.4-rc.16" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("offers an upgrade for rc → its own stable (stable > its rc per semver)", async () => {
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.4" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("offers an upgrade for a plain stable → newer stable", async () => {
+    const mods = await modulesWith({ installedVersion: "0.4.5", latest: "0.5.0" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("no upgrade when installed === latest", async () => {
+    const mods = await modulesWith({ installedVersion: "0.5.0", latest: "0.5.0" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("no upgrade when the npm probe failed (latest_version null)", async () => {
+    const mods = await modulesWith({ installedVersion: "0.5.0", latest: null });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.latest_version).toBeNull();
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("installed_version reflects the LIVE on-disk version, not a stale services.json cache (hub#243)", async () => {
+    // services.json cache lags the bun-linked checkout: cache says 0.5.4-rc.15
+    // (the live symptom) while package.json on disk is already 0.6.4-rc.15.
+    // The admin view must show what's actually installed.
+    const mods = await modulesWith({
+      installedVersion: "0.5.4-rc.15",
+      latest: "0.6.3",
+      readInstalledVersion: (dir) => (dir === "/install/dir/vault" ? "0.6.4-rc.15" : null),
+    });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    // And with the corrected current, @latest 0.6.3 is still a downgrade → no offer.
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("falls back to the services.json version when the live read returns null", async () => {
+    const mods = await modulesWith({
+      installedVersion: "0.6.4-rc.15",
+      latest: "0.6.4-rc.16",
+      readInstalledVersion: () => null,
+    });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("isUpgradeAvailable: semver-aware, fail-closed on unparseable + nulls", () => {
+    // strictly-newer → true
+    expect(isUpgradeAvailable("0.4.5", "0.5.0")).toBe(true);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.4-rc.16")).toBe(true);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.4")).toBe(true); // stable > its rc
+    // same / older → false
+    expect(isUpgradeAvailable("0.5.0", "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.3")).toBe(false); // the live downgrade
+    expect(isUpgradeAvailable("0.6.4", "0.6.4-rc.15")).toBe(false); // stable → its rc
+    // nulls → false (not installed / probe failed)
+    expect(isUpgradeAvailable(null, "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.5.0", null)).toBe(false);
+    // unparseable → false (fail-closed: never offer a move we can't verify)
+    expect(isUpgradeAvailable("not-a-version", "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.5.0", "garbage")).toBe(false);
+  });
+
+  test("defaultReadInstalledVersion reads package.json version + tolerates missing/bad files", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "phub-live-ver-"));
+    try {
+      writeFileSync(join(tmp, "package.json"), JSON.stringify({ version: "0.6.4-rc.15" }));
+      expect(defaultReadInstalledVersion(tmp)).toBe("0.6.4-rc.15");
+      // Missing dir / no package.json → null.
+      expect(defaultReadInstalledVersion(join(tmp, "does-not-exist"))).toBeNull();
+      // Malformed JSON → null (no throw).
+      writeFileSync(join(tmp, "package.json"), "{ not json");
+      expect(defaultReadInstalledVersion(tmp)).toBeNull();
+      // No version field → null.
+      writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "x" }));
+      expect(defaultReadInstalledVersion(tmp)).toBeNull();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
   test("includes supervisor status + pid when a supervisor is injected", async () => {
     writeManifest(h.manifestPath, [
       {