Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
13.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { request } from "node:http";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { JSONRPC_VERSION, PROTOCOL_VERSION, startHttp } from "../../src/mcp/index.ts";
import { MCPServer } from "../../src/mcp/server.ts";
import { mintAgentToken } from "../../src/core/brain/secrets/token-store.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";

interface RawResponse {
  readonly status: number;
  readonly body: string;
}

/**
 * Raw HTTP request with fully-controllable headers (fetch forbids overriding
 * Host). Used to exercise the DNS-rebinding guard.
 */
function rawRequest(
  url: string,
  opts: { method?: string; headers?: Record<string, string>; body?: string } = {},
): Promise<RawResponse> {
  const u = new URL(url);
  return new Promise((resolve, reject) => {
    const req = request(
      {
        hostname: u.hostname,
        port: u.port,
        path: u.pathname,
        method: opts.method ?? "GET",
        headers: opts.headers ?? {},
      },
      (res) => {
        let body = "";
        res.on("data", (c) => (body += c));
        res.on("end", () => resolve({ status: res.statusCode ?? 0, body }));
      },
    );
    req.on("error", reject);
    if (opts.body !== undefined) req.write(opts.body);
    req.end();
  });
}

interface JsonObject {
  readonly [key: string]: any;
}

async function responseJson(res: Response): Promise<JsonObject> {
  return (await res.json()) as JsonObject;
}

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-mcp-http-"));
  // An unswitched machine: a vault with no `Brain/` is a store-only fresh
  // install (design D14 item 1), whose writes need a device id and a store.
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function rpc(method: string, id: number, params: Record<string, unknown> = {}) {
  return { jsonrpc: JSONRPC_VERSION, id, method, params };
}

async function post(
  url: string,
  body: unknown,
  opts: { key?: string; accept?: string; header?: "authorization" | "x-api-key" } = {},
): Promise<Response> {
  const headers: Record<string, string> = {
    "content-type": "application/json",
    accept: opts.accept ?? "application/json",
  };
  if (opts.key !== undefined) {
    if (opts.header === "x-api-key") headers["x-api-key"] = opts.key;
    else headers.authorization = `Bearer ${opts.key}`;
  }
  return fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
}

describe("Streamable HTTP MCP transport", () => {
  test("refuses to bind a non-loopback host without an API key", async () => {
    await expect(startHttp({ vault }, { host: "0.0.0.0", port: 0 })).rejects.toThrow(/api-key/i);
  });

  test("starts on loopback without an API key (guards are the baseline)", async () => {
    const handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
    try {
      const res = await post(
        handle.url,
        rpc("initialize", 1, { protocolVersion: PROTOCOL_VERSION, capabilities: {} }),
      );
      expect(res.status).toBe(200);
      const body = await responseJson(res);
      expect(body.result.protocolVersion).toBe(PROTOCOL_VERSION);
    } finally {
      await handle.close();
    }
  });

  test("GET /health returns 200 without a bearer", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await rawRequest(`${handle.url}/health`, { method: "GET" });
      expect(res.status).toBe(200);
      expect(JSON.parse(res.body).status).toBe("ok");
    } finally {
      await handle.close();
    }
  });

  test("rejects a mismatched Host header (DNS-rebinding guard)", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await rawRequest(handle.url, {
        method: "POST",
        headers: { host: "evil.example.com", "content-type": "application/json" },
        body: JSON.stringify(rpc("ping", 1)),
      });
      expect(res.status).toBe(403);
      expect(res.body).toContain("Host not allowed");
    } finally {
      await handle.close();
    }
  });

  test("rejects a cross-origin Origin header", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await rawRequest(handle.url, {
        method: "POST",
        headers: {
          host: `127.0.0.1:${handle.port}`,
          origin: "http://evil.example.com",
          authorization: "Bearer secret",
          "content-type": "application/json",
        },
        body: JSON.stringify(rpc("ping", 1)),
      });
      expect(res.status).toBe(403);
      expect(res.body).toContain("Origin not allowed");
    } finally {
      await handle.close();
    }
  });

  test("a non-loopback (0.0.0.0) bind accepts the machine's real Host/Origin", async () => {
    // Binding a wildcard is an explicit network exposure gated by the mandatory
    // bearer; the DNS-rebinding Host/Origin guard (a loopback-only concern)
    // must not reject the machine's real IP / DNS Host, which would make
    // 0.0.0.0 unusable. We connect over loopback but present a foreign Host.
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "0.0.0.0", port: 0 });
    try {
      const res = await rawRequest(`http://127.0.0.1:${handle.port}`, {
        method: "POST",
        headers: {
          host: "box.internal.example",
          origin: "http://box.internal.example",
          authorization: "Bearer secret",
          "content-type": "application/json",
        },
        body: JSON.stringify(rpc("ping", 1)),
      });
      expect(res.status).toBe(200);
    } finally {
      await handle.close();
    }
  });

  test("a non-loopback bind still enforces the bearer", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "0.0.0.0", port: 0 });
    try {
      const res = await rawRequest(`http://127.0.0.1:${handle.port}`, {
        method: "POST",
        headers: { host: "box.internal.example", "content-type": "application/json" },
        body: JSON.stringify(rpc("ping", 1)),
      });
      expect(res.status).toBe(401);
    } finally {
      await handle.close();
    }
  });

  test("accepts a loopback Origin", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await rawRequest(handle.url, {
        method: "POST",
        headers: {
          host: `127.0.0.1:${handle.port}`,
          origin: `http://127.0.0.1:${handle.port}`,
          authorization: "Bearer secret",
          "content-type": "application/json",
        },
        body: JSON.stringify(rpc("ping", 1)),
      });
      expect(res.status).toBe(200);
    } finally {
      await handle.close();
    }
  });

  test("uses generic 401 for missing and wrong API keys", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const req = rpc("ping", 1);
      const missing = await post(handle.url, req);
      const wrong = await post(handle.url, req, { key: "wrong" });
      expect(missing.status).toBe(401);
      expect(wrong.status).toBe(401);
      expect(await missing.text()).toBe("Unauthorized\n");
      expect(await wrong.text()).toBe("Unauthorized\n");
    } finally {
      await handle.close();
    }
  });

  test("the bearer accepts any run of whitespace before the key and nothing after it", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const send = (authorization: string) =>
        fetch(handle.url, {
          method: "POST",
          headers: {
            "content-type": "application/json",
            accept: "application/json",
            authorization,
          },
          body: JSON.stringify(rpc("ping", 1)),
        });
      expect((await send("Bearer \t  secret")).status).toBe(200);
      expect((await send(`Bearer ${" ".repeat(64)}`)).status).toBe(401);
    } finally {
      await handle.close();
    }
  });

  test("authenticated initialize and tools/list round-trip through JSON responses", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const initRes = await post(
        handle.url,
        rpc("initialize", 1, { protocolVersion: PROTOCOL_VERSION, capabilities: {} }),
        { key: "secret" },
      );
      expect(initRes.status).toBe(200);
      // No session header. One MCPServer instance serves every request on
      // this transport and nothing is keyed by a session, so an id here
      // would advertise state that does not exist - and the id that used
      // to be minted was never read back on any later request.
      expect(initRes.headers.get("mcp-session-id")).toBeNull();
      const init = await responseJson(initRes);
      expect(init.result.protocolVersion).toBe(PROTOCOL_VERSION);

      const listRes = await post(handle.url, rpc("tools/list", 2), { key: "secret" });
      const list = await responseJson(listRes);
      expect(list.jsonrpc).toBe(JSONRPC_VERSION);
      expect(Array.isArray(list.result.tools)).toBe(true);
      expect(list.result.tools.length).toBeGreaterThan(0);
    } finally {
      await handle.close();
    }
  });

  test("returns one SSE event when the client accepts event-stream", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await post(handle.url, rpc("ping", 3), {
        key: "secret",
        accept: "application/json, text/event-stream",
      });
      expect(res.status).toBe(200);
      expect(res.headers.get("content-type") ?? "").toContain("text/event-stream");
      const text = await res.text();
      expect(text).toContain("event: message");
      expect(text).toContain('"id":3');
    } finally {
      await handle.close();
    }
  });

  test("rejects JSON-RPC batch bodies like stdio", async () => {
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await post(handle.url, [rpc("ping", 1)], { key: "secret" });
      const body = await responseJson(res);
      expect(body.error.code).toBe(-32600);
      expect(body.error.message).toContain("batch requests are not supported");
    } finally {
      await handle.close();
    }
  });

  test("a throw that escapes the dispatch is classified, redacted and named", async () => {
    // The catch-all behind `handleHttpRequest`: the one path where raw
    // exception prose could leave without the redactor or a code.
    const dispatch = spyOn(MCPServer.prototype, "handleRequest").mockImplementation(() => {
      throw new Error(`boom at ${join(vault, "private.md")}`);
    });
    const lines: string[] = [];
    const stderr = spyOn(process.stderr, "write").mockImplementation((chunk) => {
      lines.push(String(chunk));
      return true;
    });
    const handle = await startHttp({ vault }, { apiKey: "secret", host: "127.0.0.1", port: 0 });
    try {
      const res = await post(handle.url, rpc("ping", 4), { key: "secret" });
      const body = await responseJson(res);
      expect(body.error.code).toBe(-32603);
      expect(body.error.data).toEqual({ code: "internal_error" });
      expect(body.error.message).toStartWith("internal error: boom at ");
      expect(body.error.message).not.toContain(vault);
      expect(lines).toEqual(["warning: unclassified tool error mapped to internal_error: Error\n"]);
    } finally {
      stderr.mockRestore();
      dispatch.mockRestore();
      await handle.close();
    }
  });
});

// Identity-positive cases only (write-side-trust, Task 7): a minted
// per-agent token authenticates exactly where the shared key does. The
// per-caller identity behaviour lives in `http-token-auth.test.ts` and
// the owner-scope suite; this block pins only the transport acceptance.
describe("HTTP transport with a minted agent token", () => {
  test("a minted token round-trips initialize and tools/list like the shared key", async () => {
    const { tokenMaterial } = mintAgentToken(vault, "mcp_token_transport", "transport-agent");
    const handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
    try {
      const initRes = await post(
        handle.url,
        rpc("initialize", 1, { protocolVersion: PROTOCOL_VERSION, capabilities: {} }),
        { key: tokenMaterial },
      );
      expect(initRes.status).toBe(200);
      const init = await responseJson(initRes);
      expect(init.result.protocolVersion).toBe(PROTOCOL_VERSION);
      const listRes = await post(handle.url, rpc("tools/list", 2), { key: tokenMaterial });
      const list = await responseJson(listRes);
      expect(Array.isArray(list.result.tools)).toBe(true);
    } finally {
      await handle.close();
    }
  });

  test("a token through x-api-key authenticates; an unknown credential does not", async () => {
    const { tokenMaterial } = mintAgentToken(vault, "mcp_token_transport", "transport-agent");
    const handle = await startHttp(
      { vault },
      { apiKey: fakeCredential("hdr", "-key-", "44b2"), host: "127.0.0.1", port: 0 },
    );
    try {
      const viaHeader = await post(handle.url, rpc("ping", 1), {
        key: tokenMaterial,
        header: "x-api-key",
      });
      expect(viaHeader.status).toBe(200);
      const unknown = await post(handle.url, rpc("ping", 2), {
        key: fakeCredential("osbt_", "unknown-transport"),
      });
      expect(unknown.status).toBe(401);
    } finally {
      await handle.close();
    }
  });
});