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.

14.3 KB
Raw Blame
// Gate order for the update routes: verifyAuth -> demo 403 -> rate limit ->
// action allowlist -> the lib -> audit. The update service itself is mocked
// here (its behaviour is covered in lib/managed-apps/update.test.ts) so these
// tests are only about the gates, the status codes and the wire shape — and so
// that nothing in this file can start a job or spawn a CLI.
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ManagedAppJob } from "@/lib/managed-apps/types";

vi.mock("server-only", () => ({}));

const demo = vi.hoisted(() => ({ value: false }));
const authed = vi.hoisted(() => ({ value: true }));

vi.mock("@/lib/agent/server", () => ({ verifyAuth: async () => authed.value }));
// The actor is the approved device behind the session — every destructive line
// in this trail has to be able to answer "by whom", and reading a real cookie
// here would need a request scope these unit calls do not have.
const actor = vi.hoisted(() => ({ value: "device-7f3a" as string | null }));
vi.mock("@/lib/auth/require-session", () => ({ getSessionActor: async () => actor.value }));
vi.mock("@/lib/demo", () => ({
  get IS_DEMO() {
    return demo.value;
  },
}));
// The real audit appends to ~/.mso/audit.log — the OPERATOR's, since this
// runs as them. Spied instead of written. The limiter is faked so the budget
// one test spends cannot leak into the next (it is process-global and has no
// reset); rate-limit.test.ts covers the counting itself.
const limited = vi.hoisted(() => ({ value: false }));
vi.mock("@/lib/host/audit-api", () => ({ audit: vi.fn(async () => undefined) }));
vi.mock("@/lib/host/limits-api", () => ({ rateLimited: vi.fn(() => limited.value) }));
// The lifecycle route shares this trail (and audited no actor either), so it is
// exercised here rather than left to be the one privileged route with no test.
vi.mock("@/lib/managed-apps/manager", () => ({ getManagedApp: vi.fn(), performManagedAppAction: vi.fn() }));
vi.mock("@/lib/managed-apps/update", () => ({
  cachedUpdateStatus: vi.fn(),
  checkUpdate: vi.fn(),
  startUpdate: vi.fn(),
  setChannel: vi.fn(),
  startRollback: vi.fn(),
  startUninstall: vi.fn(),
}));

const { audit } = await import("@/lib/host/audit-api");
const { rateLimited } = await import("@/lib/host/limits-api");
const service = await import("@/lib/managed-apps/update");
const { GET, POST } = await import("./[id]/update/route");
const jobRoute = await import("./[id]/jobs/[jobId]/route");
const lifecycleRoute = await import("./[id]/route");
const manager = await import("@/lib/managed-apps/manager");

const ctx = (id = "hermes") => ({ params: Promise.resolve({ id }) });
const post = (body: unknown, id = "hermes") =>
  POST(new Request("http://localhost/api/v1/managed-apps/x/update", { method: "POST", body: JSON.stringify(body) }), ctx(id));
const get = (id = "hermes") => GET(new Request("http://localhost/api/v1/managed-apps/x/update"), ctx(id));

const job = (over: Partial<ManagedAppJob> = {}): ManagedAppJob =>
  ({ id: "a".repeat(24), applicationId: "hermes", kind: "update", argv: ["/usr/bin/hermes", "update", "--yes"], status: "running", log: "", logOffset: 0, ...over }) as ManagedAppJob;

beforeEach(() => {
  demo.value = false;
  authed.value = true;
  limited.value = false;
  actor.value = "device-7f3a";
  vi.mocked(audit).mockClear();
  vi.mocked(rateLimited).mockClear();
  vi.mocked(manager.performManagedAppAction).mockReset();
  for (const fn of Object.values(service)) vi.mocked(fn).mockReset();
});

describe("the gates, in order", () => {
  it("401s both verbs without a session", async () => {
    authed.value = false;
    expect((await get()).status).toBe(401);
    expect((await post({ action: "check" })).status).toBe(401);
    expect(service.checkUpdate).not.toHaveBeenCalled();
  });

  it("403s every destructive action in demo mode, but still answers a read", async () => {
    demo.value = true;
    expect((await post({ action: "apply" })).status).toBe(403);
    expect(service.startUpdate).not.toHaveBeenCalled();
  });

  it("404s an application id that is not in the catalog", async () => {
    expect((await get("hermes-evil")).status).toBe(404);
    expect((await post({ action: "apply" }, "../../etc")).status).toBe(404);
  });

  it("400s an action outside the allowlist, including one that only looks like a verb", async () => {
    for (const action of ["install", "reset", "wizard", "", 7, undefined]) {
      const response = await post({ action });
      expect(response.status).toBe(400);
      expect(await response.json()).toEqual({ error: "unsupported managed application action" });
    }
    expect(service.startUpdate).not.toHaveBeenCalled();
  });

  it("429s when the limiter says so, on the same per-app bucket the lifecycle route uses", async () => {
    vi.mocked(service.startUpdate).mockResolvedValue(job());
    limited.value = true;
    expect((await post({ action: "apply" })).status).toBe(429);
    expect(service.startUpdate).not.toHaveBeenCalled();
    // One budget per app, not per endpoint — `managed-app:<id>` is the key
    // [id]/route.ts already spends for start/stop/restart/backup.
    expect(rateLimited).toHaveBeenCalledWith("managed-app:hermes", 12, 60_000);
    // The PROBE has its own, because it spawns the CLI and git-fetches twice.
    // A burst of checks must not spend the budget an uninstall needs.
    expect((await post({ action: "check" })).status).toBe(429);
    expect(rateLimited).toHaveBeenLastCalledWith("managed-app-check:hermes", 10, 60_000);
  });
});

describe("what each action answers with", () => {
  // The GET sits OUTSIDE the CSRF gate (proxy.ts covers mutating verbs only)
  // and the session cookie is Domain=mso.example.com, so any sibling origin can
  // make a browser send it. If it probed, that would be a blind cross-origin
  // trigger for `hermes update --check` — two git fetches in the operator's
  // checkout. It reads the cache; the probe is a POST, behind the gate.
  it("serves the cache on a GET and never probes, however cold the cache is", async () => {
    const cached = { applicationId: "hermes", currentVersion: "v1", checkedAt: null };
    vi.mocked(service.cachedUpdateStatus).mockReturnValue(cached as never);

    expect(await (await get()).json()).toMatchObject({ currentVersion: "v1" });
    expect(service.cachedUpdateStatus).toHaveBeenCalledWith("hermes");
    expect(service.checkUpdate).not.toHaveBeenCalled();
    // Nothing to rate-limit either: a read of a Map is not a spawn.
    expect(rateLimited).not.toHaveBeenCalled();
  });

  it("probes only on POST, and forces a fresh one", async () => {
    const status = { applicationId: "hermes", currentVersion: "v1", updateAvailable: true };
    vi.mocked(service.checkUpdate).mockResolvedValue(status as never);
    expect(await (await post({ action: "check" })).json()).toEqual({ status });
    expect(service.checkUpdate).toHaveBeenLastCalledWith("hermes", true);
  });

  it("answers 202 with the job record, and passes only validated option types through", async () => {
    vi.mocked(service.startUpdate).mockResolvedValue(job());
    const response = await post({ action: "apply", channel: "beta", tag: "2026.7.1-2", dryRun: true, noRestart: "yes" });

    expect(response.status).toBe(202);
    expect(await response.json()).toMatchObject({ job: { id: "a".repeat(24) } });
    // `noRestart: "yes"` is not `true`, so it is not a flag. Nothing is coerced.
    expect(service.startUpdate).toHaveBeenCalledWith("hermes", { channel: "beta", tag: "2026.7.1-2", branch: undefined, dryRun: true, noRestart: false });
  });

  it("400s a field of the wrong type instead of stringifying it into an argv", async () => {
    const response = await post({ action: "apply", channel: { toString: "beta" } });
    expect(response.status).toBe(400);
    expect(service.startUpdate).not.toHaveBeenCalled();
  });

  it("maps the lock to 409 and a bad confirmation to 400", async () => {
    vi.mocked(service.startUpdate).mockRejectedValue(new Error("another operation is already running"));
    expect((await post({ action: "apply" })).status).toBe(409);

    vi.mocked(service.startUninstall).mockRejectedValue(new Error("uninstall confirmation does not match the application id"));
    const refused = await post({ action: "uninstall", confirm: "yes" });
    expect(refused.status).toBe(400);
    expect(await refused.json()).toMatchObject({ error: expect.stringContaining("confirmation") });
  });

  it("requires a backup id for a rollback and a channel for a channel switch", async () => {
    expect((await post({ action: "rollback" })).status).toBe(400);
    expect(service.startRollback).not.toHaveBeenCalled();
    expect((await post({ action: "channel" })).status).toBe(400);
    expect(service.setChannel).not.toHaveBeenCalled();
  });

  it("forwards the pin and the confirmation exactly as sent", async () => {
    vi.mocked(service.startRollback).mockResolvedValue(job({ kind: "restore" }));
    await post({ action: "rollback", backupId: "2026-07-25T10-11-12-345Z", pin: "2026.7.1-2" });
    expect(service.startRollback).toHaveBeenCalledWith("hermes", "2026-07-25T10-11-12-345Z", "2026.7.1-2");

    vi.mocked(service.startUninstall).mockResolvedValue(job({ kind: "uninstall" }));
    await post({ action: "uninstall", confirm: "hermes", dryRun: true });
    expect(service.startUninstall).toHaveBeenCalledWith("hermes", "hermes", true);
  });
});

describe("the audit trail", () => {
  it("records enough to reconstruct the operation, including the argv that ran", async () => {
    vi.mocked(service.startUpdate).mockResolvedValue(job());
    await post({ action: "apply", channel: "beta" });

    expect(audit).toHaveBeenCalledWith(
      expect.objectContaining({
        action: "managed-app.action",
        target: "hermes",
        // WHO. 29 of the 34 audit() calls under /api/v1 carry this — including
        // fs/mkdir — and the most destructive actions in the product did not.
        actor: "device-7f3a",
        ok: true,
        detail: "update.apply",
        meta: expect.objectContaining({ jobId: "a".repeat(24), argv: "/usr/bin/hermes update --yes", channel: "beta" }),
      }),
    );
  });

  it("records the refusal too, with why", async () => {
    vi.mocked(service.startUninstall).mockRejectedValue(new Error("hermes is not installed"));
    await post({ action: "uninstall", confirm: "hermes" });

    expect(audit).toHaveBeenCalledWith(
      expect.objectContaining({ actor: "device-7f3a", ok: false, detail: "update.uninstall", meta: expect.objectContaining({ reason: "hermes is not installed" }) }),
    );
  });

  it("writes the outcome line too, once, so the trail says whether it worked", async () => {
    // Job records are pruned at 20 per app / 30 days, so without this the log
    // said an uninstall had been LAUNCHED and nothing anywhere said how it
    // ended. The line carries the same actor as the launch, matched on jobId.
    const jobs = await import("@/lib/managed-apps/jobs");
    const finished = job({ kind: "uninstall", status: "succeeded", exitCode: 0, endedAt: "2026-07-25T11:00:00.000Z" });
    vi.mocked(service.startUninstall).mockResolvedValue(finished);
    await post({ action: "uninstall", confirm: "hermes" });
    vi.spyOn(jobs, "readManagedAppJob").mockResolvedValue(finished);

    const poll = () => jobRoute.GET(new Request("http://localhost/x"), { params: Promise.resolve({ id: "hermes", jobId: finished.id }) });
    expect((await poll()).status).toBe(200);
    expect((await poll()).status).toBe(200);

    const completions = vi.mocked(audit).mock.calls.filter(([entry]) => entry.detail?.startsWith("job."));
    expect(completions).toHaveLength(1); // polled twice, audited once
    expect(completions[0][0]).toMatchObject({
      action: "managed-app.action",
      target: "hermes",
      actor: "device-7f3a",
      ok: true,
      detail: "job.uninstall.succeeded",
      meta: { jobId: finished.id, exitCode: 0, endedAt: "2026-07-25T11:00:00.000Z" },
    });
  });

  it("records a job that ended badly as such, and only once it has ended", async () => {
    const jobs = await import("@/lib/managed-apps/jobs");
    const running = job({ id: "c".repeat(24), kind: "update", status: "running" });
    vi.spyOn(jobs, "readManagedAppJob").mockResolvedValue(running);
    const poll = (id: string) => jobRoute.GET(new Request("http://localhost/x"), { params: Promise.resolve({ id: "hermes", jobId: id }) });
    await poll(running.id);
    expect(vi.mocked(audit).mock.calls.filter(([entry]) => entry.detail?.startsWith("job."))).toHaveLength(0);

    vi.mocked(jobs.readManagedAppJob).mockResolvedValue({ ...running, status: "interrupted", error: "the cockpit restarted" });
    await poll(running.id);
    expect(audit).toHaveBeenLastCalledWith(
      // No actor: this process never took the request that started it (a job
      // that outlived a deploy). `null` is the honest answer, not a guess.
      expect.objectContaining({ ok: false, actor: null, detail: "job.update.interrupted", meta: expect.objectContaining({ error: "the cockpit restarted" }) }),
    );
  });
});

describe("the lifecycle route shares the trail", () => {
  const act = (action: string) =>
    lifecycleRoute.POST(new Request("http://localhost/x", { method: "POST", body: JSON.stringify({ action }) }), ctx());

  it("attributes a restart and a failed backup to the device that asked", async () => {
    vi.mocked(manager.performManagedAppAction).mockResolvedValue({ id: "hermes" } as never);
    expect((await act("restart")).status).toBe(200);
    expect(audit).toHaveBeenLastCalledWith({ action: "managed-app.action", target: "hermes", actor: "device-7f3a", ok: true, detail: "restart" });

    vi.mocked(manager.performManagedAppAction).mockRejectedValue(new Error("unit is masked"));
    actor.value = null; // an unauthenticated caller cannot reach here, but null is the honest answer
    expect((await act("backup")).status).toBe(409);
    expect(audit).toHaveBeenLastCalledWith({ action: "managed-app.action", target: "hermes", actor: null, ok: false, detail: "backup" });
  });
});

describe("job polling", () => {
  it("404s a job that belongs to another app rather than serving its transcript", async () => {
    const jobs = await import("@/lib/managed-apps/jobs");
    vi.spyOn(jobs, "readManagedAppJob").mockResolvedValue(job({ applicationId: "openclaw" }));
    const response = await jobRoute.GET(new Request("http://localhost/x?since=10"), {
      params: Promise.resolve({ id: "hermes", jobId: "a".repeat(24) }),
    });
    expect(response.status).toBe(404);
  });
});