Skip to content
Python
14.3 KB
Raw Blame
import * as fs from "node:fs/promises";
import {
  chmod,
  link,
  lstat,
  mkdir,
  mkdtemp,
  readdir,
  readFile,
  rename,
  rm,
  symlink,
  writeFile,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import type { BrokerDiscovery } from "@one-memory/host-bridge";
import axios from "axios";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import { inspectRecallBrokerStatus } from "./broker-status.js";

vi.mock("node:fs/promises", async (importOriginal) => {
  const actual = await importOriginal<typeof import("node:fs/promises")>();
  return { ...actual, open: vi.fn(actual.open) };
});

const receipt: BrokerDiscovery = {
  schema_version: 1,
  service: "one-memory-recall-broker",
  status: "running",
  host: "127.0.0.1",
  port: 18765,
  instance_id: "test-runtime",
  pid: 4321,
  updated_at: "2026-09-19T01:00:00.000Z",
};
const health = {
  status: "ok",
  service: "one-memory-recall-broker",
  instance_id: receipt.instance_id,
};

describe("inspectRecallBrokerStatus", () => {
  let root: string;
  let dataDir: string;
  let target: string;
  const alive = vi.fn(() => true);
  const probe = vi.fn(async (): Promise<unknown> => ({ ...health }));

  beforeEach(async () => {
    root = await mkdtemp(path.join(os.tmpdir(), "om-broker-status-"));
    dataDir = path.join(root, "selected-home");
    target = path.join(dataDir, "integrations", "cursor-broker.json");
    alive.mockReset().mockReturnValue(true);
    probe.mockReset().mockResolvedValue({ ...health });
    // An accidental use of the default transport must never reach a real service.
    vi.spyOn(axios, "get").mockRejectedValue(new Error("unexpected network"));
  });

  afterEach(async () => {
    vi.restoreAllMocks();
    vi.mocked(fs.open).mockReset();
    await rm(root, { recursive: true, force: true });
  });

  async function put(value: unknown = receipt) {
    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
    await writeFile(target, JSON.stringify(value), { mode: 0o600 });
  }

  function inspect(expectedInstanceId = receipt.instance_id) {
    return inspectRecallBrokerStatus({
      dataDir,
      expectedInstanceId,
      processIsAlive: alive,
      probeBroker: probe,
    });
  }

  it("verifies the real protocol and leaves files/metadata unchanged", async () => {
    await put();
    const before = await lstat(target);
    const bytes = await readFile(target);
    expect(await inspect()).toEqual({
      state: "running",
      code: "broker_verified",
      instanceId: receipt.instance_id,
      host: "127.0.0.1",
      port: 18765,
    });
    expect(alive).toHaveBeenCalledWith(4321);
    expect(probe).toHaveBeenCalledWith(receipt);
    expect(await readFile(target)).toEqual(bytes);
    const after = await lstat(target);
    expect([after.ino, after.mode, after.mtimeMs, after.ctimeMs]).toEqual([
      before.ino,
      before.mode,
      before.mtimeMs,
      before.ctimeMs,
    ]);
    expect(await readdir(path.dirname(target))).toEqual(["cursor-broker.json"]);
    expect(axios.get).not.toHaveBeenCalled();
  });

  it("does not create an absent home or search a different discovery path", async () => {
    expect(await inspect()).toEqual({
      state: "stopped",
      code: "broker_discovery_missing",
    });
    expect(await readdir(root)).toEqual([]);
    await mkdir(dataDir);
    await writeFile(path.join(dataDir, "broker.json"), JSON.stringify(receipt));
    expect(await inspect()).toEqual({
      state: "stopped",
      code: "broker_discovery_missing",
    });
    expect(await readdir(dataDir)).toEqual(["broker.json"]);
    expect(alive).not.toHaveBeenCalled();
    expect(probe).not.toHaveBeenCalled();
  });

  it("reports a valid stopped receipt without checking PID or probing", async () => {
    await put({ ...receipt, status: "stopped", port: null });
    expect(await inspect()).toEqual({
      state: "stopped",
      code: "broker_stopped",
    });
    expect(alive).not.toHaveBeenCalled();
    expect(probe).not.toHaveBeenCalled();
  });

  it("reports a validated dead PID as stopped without probing", async () => {
    await put();
    alive.mockReturnValue(false);
    expect(await inspect()).toEqual({
      state: "stopped",
      code: "broker_process_dead",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it.each(["running", "stopped"])(
    "rejects wrong instance before %s/PID checks",
    async (status) => {
      await put({
        ...receipt,
        status,
        port: status === "stopped" ? null : receipt.port,
      });
      alive.mockReturnValue(false);
      expect(await inspect("other-runtime")).toEqual({
        state: "untrusted",
        code: "broker_instance_mismatch",
      });
      expect(alive).not.toHaveBeenCalled();
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it.each(["", " ", "test\nsecret"])(
    "rejects invalid expected identity %j",
    async (identity) => {
      expect(await inspect(identity)).toEqual({
        state: "untrusted",
        code: "broker_expected_instance_invalid",
      });
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it.each([
    { schema_version: 2 },
    { service: "one-memory-core" },
    { host: "localhost" },
    { host: "::1" },
    { host: "127.0.0.2" },
    { host: "https://example.invalid" },
    { port: null },
    { port: 0 },
    { port: -1 },
    { port: 65536 },
    { port: 12.5 },
    { port: "18765" },
    { pid: 0 },
    { pid: 1 },
    { pid: -4321 },
    { pid: 2.5 },
    { pid: "4321" },
    { pid: Number.MAX_SAFE_INTEGER },
    { instance_id: "" },
    { instance_id: " test-runtime " },
    { updated_at: "" },
    { updated_at: "invalid" },
    { status: "starting" },
    { status: "stopped", port: 18765 },
  ])(
    "rejects malformed identity %j without PID or HTTP calls",
    async (change) => {
      await put({ ...receipt, ...change });
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_invalid",
      });
      expect(alive).not.toHaveBeenCalled();
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it.each([null, [], {}, "secret"])(
    "rejects non-receipt JSON %j",
    async (value) => {
      await put(value);
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_invalid",
      });
    },
  );

  it("rejects partial JSON without disclosing the document", async () => {
    await put();
    await writeFile(target, '{"token":"private-marker"');
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_invalid",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it("accepts 16KiB but refuses any extra byte before probing", async () => {
    await put();
    await writeFile(target, JSON.stringify(receipt).padEnd(16 * 1024, " "));
    expect((await inspect()).state).toBe("running");
    probe.mockClear();
    await writeFile(target, JSON.stringify(receipt).padEnd(16 * 1024 + 1, " "));
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it.each([0o644, 0o620, 0o601, 0o000])(
    "refuses insecure/unreadable file mode %s",
    async (mode) => {
      await put();
      await chmod(target, mode);
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_unsafe",
      });
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it("refuses a different owner without changing real file ownership", async () => {
    await put();
    const uid = process.getuid?.();
    if (uid === undefined) throw new Error("POSIX test requires getuid");
    vi.spyOn(process, "getuid").mockReturnValue(uid + 1);
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it.each([false, true])(
    "refuses a discovery symlink, including dangling=%s",
    async (dangling) => {
      await put();
      const other = path.join(root, "other.json");
      await rename(target, other);
      if (dangling) await rm(other);
      await symlink(other, target);
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_unsafe",
      });
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it("refuses a hard-linked file", async () => {
    await put();
    await link(target, path.join(root, "alias.json"));
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it("refuses a directory at the discovery path", async () => {
    await mkdir(target, { recursive: true });
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
  });

  it("does not follow an integrations symlink to another home", async () => {
    await put();
    const other = path.join(root, "other-integrations");
    await rename(path.dirname(target), other);
    await symlink(other, path.dirname(target));
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it("does not classify ENOTDIR as missing", async () => {
    await mkdir(dataDir);
    await writeFile(path.dirname(target), "not a directory");
    expect((await inspect()).state).toBe("untrusted");
    expect(probe).not.toHaveBeenCalled();
  });

  it("sanitizes PID inspection failure, never treating it as dead", async () => {
    await put();
    alive.mockImplementation(() => {
      throw new Error("private PID detail");
    });
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_process_unverifiable",
    });
    expect(probe).not.toHaveBeenCalled();
  });

  it("sanitizes probe failure as unhealthy", async () => {
    await put();
    probe.mockRejectedValue(new Error("token=private-marker"));
    expect(await inspect()).toEqual({
      state: "unhealthy",
      code: "broker_identity_unavailable",
    });
  });

  it.each([
    undefined,
    null,
    {},
    [],
    { ...health, status: "failed" },
    { ...health, service: "one-memory-core" },
    { ...health, instance_id: "another-runtime" },
  ])("never trusts an invalid health body %j", async (body) => {
    await put();
    probe.mockResolvedValue(body);
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_identity_mismatch",
    });
  });

  it("returns only public fields and passes no unknown receipt fields to the probe", async () => {
    await put({
      ...receipt,
      token: "private-marker",
      arbitrary: "private-value",
    });
    probe.mockResolvedValue({ ...health, token: "another-private-marker" });
    expect(await inspect()).toEqual({
      state: "running",
      code: "broker_verified",
      instanceId: receipt.instance_id,
      host: receipt.host,
      port: receipt.port,
    });
    expect(probe).toHaveBeenCalledWith(receipt);
  });

  it("uses bounded loopback axios without redirects/proxy and validates its body", async () => {
    await put();
    vi.mocked(axios.get).mockResolvedValue({ data: health });
    expect(
      (
        await inspectRecallBrokerStatus({
          dataDir,
          expectedInstanceId: receipt.instance_id,
          processIsAlive: alive,
        })
      ).state,
    ).toBe("running");
    expect(axios.get).toHaveBeenCalledWith(
      "http://127.0.0.1:18765/health",
      expect.objectContaining({
        timeout: 1000,
        maxRedirects: 0,
        proxy: false,
        maxContentLength: 16 * 1024,
      }),
    );
    vi.mocked(axios.get).mockResolvedValue({
      data: { ...health, service: "fake" },
    });
    expect(
      (
        await inspectRecallBrokerStatus({
          dataDir,
          expectedInstanceId: receipt.instance_id,
          processIsAlive: alive,
        })
      ).state,
    ).toBe("untrusted");
  });

  it.each(["replace", "remove", "chmod"])(
    "fails closed if discovery changes during probe: %s",
    async (change) => {
      await put();
      probe.mockImplementation(async () => {
        if (change === "remove") await rm(target);
        else if (change === "chmod") await chmod(target, 0o644);
        else {
          await rm(target);
          await put({ ...receipt, instance_id: "replacement" });
        }
        return health;
      });
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_changed",
      });
    },
  );

  it("does not report running if the PID dies during the probe", async () => {
    await put();
    alive.mockReturnValueOnce(true).mockReturnValue(false);
    expect(await inspect()).toEqual({
      state: "stopped",
      code: "broker_process_dead",
    });
  });

  it.each(["EACCES", "EIO", "EMFILE"])(
    "sanitizes file-open error %s without probing",
    async (code) => {
      await put();
      vi.mocked(fs.open).mockRejectedValueOnce(
        Object.assign(new Error("private path/body"), { code }),
      );
      expect(await inspect()).toEqual({
        state: "untrusted",
        code: "broker_discovery_unreadable",
      });
      expect(probe).not.toHaveBeenCalled();
    },
  );

  it.each(["ESRCH", "EPERM", "EIO"])(
    "default PID checker distinguishes %s with signal zero only",
    async (code) => {
      await put();
      const signal = vi.spyOn(process, "kill").mockImplementation(() => {
        throw Object.assign(new Error("private process detail"), { code });
      });
      const result = await inspectRecallBrokerStatus({
        dataDir,
        expectedInstanceId: receipt.instance_id,
        probeBroker: probe,
      });
      expect(result.state).toBe(
        code === "ESRCH"
          ? "stopped"
          : code === "EPERM"
            ? "running"
            : "untrusted",
      );
      expect(signal).toHaveBeenCalledWith(4321, 0);
      expect(signal.mock.calls.every((call) => call[1] === 0)).toBe(true);
      if (code !== "EPERM") expect(probe).not.toHaveBeenCalled();
    },
  );

  it("fails closed without a verified POSIX ownership implementation", async () => {
    await put();
    vi.spyOn(process, "getuid").mockReturnValue(undefined as unknown as number);
    expect(await inspect()).toEqual({
      state: "untrusted",
      code: "broker_discovery_unsafe",
    });
    expect(probe).not.toHaveBeenCalled();
  });
});