@nexvora/mcp-server 0.3.2 → 0.4.0

package/src/__tests__/auth/oauth.test.ts

@@ -1,246 +0,0 @@
-/**
- * Unit tests for the OAuth 2.0 Device Authorization Grant login module.
- *
- * All network calls (fetch), the browser-opener (node:child_process.exec) and
- * the polling sleep are mocked so these tests run instantly without any real
- * network access or wall-clock waits.
- */
-
-import { jest } from "@jest/globals";
-
-// ── Mocks must be set up before importing the module under test ─────────────
-
-jest.unstable_mockModule("node:child_process", () => ({
-  exec: jest.fn((_cmd: string, cb?: (err: Error | null) => void) => {
-    cb?.(null);
-  }),
-}));
-
-jest.unstable_mockModule("node:os", () => ({
-  hostname: jest.fn(() => "test-host"),
-}));
-
-const mockFetch = jest.fn() as jest.MockedFunction<typeof fetch>;
-global.fetch = mockFetch as typeof fetch;
-
-// ── Now import the module under test ───────────────────────────────────────
-
-const { loginInteractive, DeviceGrantError } = await import("../../auth/oauth.js");
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-function jsonResponse(data: unknown, status = 200): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    json: () => Promise.resolve(data),
-    text: () => Promise.resolve(JSON.stringify(data)),
-  } as unknown as Response;
-}
-
-function errorJsonResponse(status: number, body: unknown): Response {
-  return {
-    ok: false,
-    status,
-    json: () => Promise.resolve(body),
-    text: () => Promise.resolve(JSON.stringify(body)),
-  } as unknown as Response;
-}
-
-function networkErrorResponse(status: number, text = "error"): Response {
-  return {
-    ok: false,
-    status,
-    json: () => Promise.reject(new Error("not json")),
-    text: () => Promise.resolve(text),
-  } as unknown as Response;
-}
-
-const AUTHORIZE_RESPONSE = {
-  device_code: "dev-code-abc",
-  user_code: "ABCD-1234",
-  verification_uri: "https://app.nxvora.online/oauth/device",
-  verification_uri_complete: "https://app.nxvora.online/oauth/device?user_code=ABCD-1234",
-  expires_in: 600,
-  interval: 0, // 0 so the test doesn't actually wait between polls
-};
-
-const TOKEN_SUCCESS = {
-  access_token: "access-token-abc",
-  refresh_token: "refresh-token-xyz",
-  token_type: "Bearer",
-  expires_in: 3600,
-};
-
-const USER = { id: "user-123" };
-
-// ── loginInteractive ───────────────────────────────────────────────────────
-
-/**
- * Drive a loginInteractive() invocation past the polling sleeps by running
- * any scheduled timers and yielding control to fetch mocks until the promise
- * settles. Uses jest fake timers so the test does not sleep in real time.
- */
-async function runLoginToCompletion<T>(promise: Promise<T>): Promise<T> {
-  // Loop while the promise is still pending. Each iteration: let queued
-  // microtasks settle, advance fake timers (firing any pending setTimeout),
-  // then yield again so the fetch mock can resolve.
-  let settled = false;
-  let result: T;
-  let err: unknown;
-  promise.then(
-    (v) => { result = v; settled = true; },
-    (e) => { err = e; settled = true; },
-  );
-  for (let i = 0; i < 50 && !settled; i++) {
-    // eslint-disable-next-line no-await-in-loop
-    await Promise.resolve();
-    // eslint-disable-next-line no-await-in-loop
-    await jest.advanceTimersByTimeAsync(10_000);
-  }
-  if (!settled) throw new Error("loginInteractive did not settle within timer budget");
-  if (err) throw err;
-  return result!;
-}
-
-describe("loginInteractive (Device Grant)", () => {
-  beforeEach(() => {
-    mockFetch.mockReset();
-    jest.useFakeTimers();
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  it("returns a Config when the first poll already succeeds", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    const config = await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-
-    expect(config.accessToken).toBe("access-token-abc");
-    expect(config.refreshToken).toBe("refresh-token-xyz");
-    expect(config.serverUrl).toBe("https://api.nxvora.online");
-    expect(config.userId).toBe("user-123");
-    expect(config.expiresAt).toBeGreaterThan(Math.floor(Date.now() / 1000));
-  });
-
-  it("calls /oauth/device/authorize with client_id, scope, device_name", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-
-    const [url, init] = mockFetch.mock.calls[0];
-    expect(url).toBe("https://api.nxvora.online/oauth/device/authorize");
-    const body = JSON.parse((init as RequestInit).body as string);
-    expect(body.client_id).toBe("nexvora-mcp-server");
-    expect(body.scope).toBe("mcp:tools offline_access");
-    expect(body.device_name).toBe("test-host");
-  });
-
-  it("calls /oauth/device/token with the device_code URN grant type", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-
-    const [url, init] = mockFetch.mock.calls[1];
-    expect(url).toBe("https://api.nxvora.online/oauth/device/token");
-    const body = JSON.parse((init as RequestInit).body as string);
-    expect(body.grant_type).toBe("urn:ietf:params:oauth:grant-type:device_code");
-    expect(body.device_code).toBe("dev-code-abc");
-    expect(body.client_id).toBe("nexvora-mcp-server");
-  });
-
-  it("keeps polling on authorization_pending until tokens are issued", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(errorJsonResponse(400, { error: "authorization_pending" }))
-      .mockResolvedValueOnce(errorJsonResponse(400, { error: "authorization_pending" }))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    const config = await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-
-    expect(config.accessToken).toBe("access-token-abc");
-    // 1 authorize + 3 token polls + 1 user-fetch = 5 calls
-    expect(mockFetch).toHaveBeenCalledTimes(5);
-  });
-
-  it("honours slow_down by continuing to poll (interval bumped internally)", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(errorJsonResponse(400, { error: "slow_down" }))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    const config = await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-
-    expect(config.accessToken).toBe("access-token-abc");
-  });
-
-  it("throws DeviceGrantError(access_denied) when the user denies", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(errorJsonResponse(400, {
-        error: "access_denied",
-        error_description: "User denied the request",
-      }));
-
-    await expect(
-      runLoginToCompletion(loginInteractive("https://api.nxvora.online")),
-    ).rejects.toMatchObject({
-      name: "DeviceGrantError",
-      code: "access_denied",
-    });
-  });
-
-  it("throws DeviceGrantError(expired_token) when the code expires", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(errorJsonResponse(400, { error: "expired_token" }));
-
-    await expect(
-      runLoginToCompletion(loginInteractive("https://api.nxvora.online")),
-    ).rejects.toBeInstanceOf(DeviceGrantError);
-  });
-
-  it("throws a descriptive error when /oauth/device/authorize returns non-2xx", async () => {
-    mockFetch.mockResolvedValueOnce(networkErrorResponse(404));
-
-    await expect(
-      runLoginToCompletion(loginInteractive("https://api.nxvora.online")),
-    ).rejects.toThrow(/Failed to start OAuth device authorization \(404\)/);
-  });
-
-  it("falls back to empty string userId when /api/users/me returns non-2xx", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(networkErrorResponse(401));
-
-    const config = await runLoginToCompletion(loginInteractive("https://api.nxvora.online"));
-    expect(config.userId).toBe("");
-  });
-
-  it("strips trailing slash from base URL", async () => {
-    mockFetch
-      .mockResolvedValueOnce(jsonResponse(AUTHORIZE_RESPONSE))
-      .mockResolvedValueOnce(jsonResponse(TOKEN_SUCCESS))
-      .mockResolvedValueOnce(jsonResponse(USER));
-
-    const config = await runLoginToCompletion(loginInteractive("https://api.nxvora.online/"));
-    expect(config.serverUrl).toBe("https://api.nxvora.online");
-    expect(mockFetch.mock.calls[0][0]).toBe(
-      "https://api.nxvora.online/oauth/device/authorize",
-    );
-  });
-});

package/src/__tests__/cache.test.ts

@@ -1,64 +0,0 @@
-import { jest } from "@jest/globals";
-
-import { TtlCache } from "../cache.js";
-
-describe("TtlCache", () => {
-  beforeEach(() => {
-    jest.useFakeTimers();
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  it("returns undefined for missing keys", () => {
-    const cache = new TtlCache<string>(1000);
-    expect(cache.get("missing")).toBeUndefined();
-  });
-
-  it("returns value within TTL", () => {
-    const cache = new TtlCache<number>(5000);
-    cache.set("key", 42);
-    jest.advanceTimersByTime(4999);
-    expect(cache.get("key")).toBe(42);
-  });
-
-  it("returns undefined after TTL expires", () => {
-    const cache = new TtlCache<number>(1000);
-    cache.set("key", 99);
-    jest.advanceTimersByTime(1001);
-    expect(cache.get("key")).toBeUndefined();
-  });
-
-  it("getOrFetch calls fn on cache miss", async () => {
-    const cache = new TtlCache<string>(5000);
-    const fn = jest.fn().mockResolvedValue("fetched");
-
-    const result = await cache.getOrFetch("key", fn);
-
-    expect(result).toBe("fetched");
-    expect(fn).toHaveBeenCalledTimes(1);
-  });
-
-  it("getOrFetch returns cached value without calling fn on hit", async () => {
-    const cache = new TtlCache<string>(5000);
-    cache.set("key", "cached");
-    const fn = jest.fn().mockResolvedValue("fetched");
-
-    const result = await cache.getOrFetch("key", fn);
-
-    expect(result).toBe("cached");
-    expect(fn).not.toHaveBeenCalled();
-  });
-
-  it("getOrFetch calls fn again after TTL expires", async () => {
-    const cache = new TtlCache<number>(1000);
-    const fn = jest.fn().mockResolvedValue(1);
-
-    await cache.getOrFetch("key", fn);
-    jest.advanceTimersByTime(1001);
-    await cache.getOrFetch("key", fn);
-
-    expect(fn).toHaveBeenCalledTimes(2);
-  });
-});

package/src/__tests__/config.test.ts

@@ -1,98 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { ConfigManager, type Config } from "../config.js";
-
-const SAMPLE_CONFIG: Config = {
-  accessToken: "access-abc",
-  refreshToken: "refresh-xyz",
-  expiresAt: 9999999999,
-  serverUrl: "https://api.nxvora.online",
-  userId: "user-001",
-};
-
-describe("ConfigManager", () => {
-  let tmpDir: string;
-  let configPath: string;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nexvora-config-test-"));
-    configPath = path.join(tmpDir, "config.json");
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  describe("read()", () => {
-    it("parses a valid config file", () => {
-      fs.writeFileSync(configPath, JSON.stringify(SAMPLE_CONFIG), "utf8");
-      const manager = new ConfigManager(configPath);
-
-      const config = manager.read();
-
-      expect(config.accessToken).toBe("access-abc");
-      expect(config.refreshToken).toBe("refresh-xyz");
-      expect(config.expiresAt).toBe(9999999999);
-      expect(config.serverUrl).toBe("https://api.nxvora.online");
-      expect(config.userId).toBe("user-001");
-    });
-
-    it("throws when file does not exist", () => {
-      const manager = new ConfigManager(path.join(tmpDir, "nonexistent.json"));
-      expect(() => manager.read()).toThrow();
-    });
-  });
-
-  describe("write()", () => {
-    it("writes config as pretty-printed JSON", () => {
-      const manager = new ConfigManager(configPath);
-      manager.write(SAMPLE_CONFIG);
-
-      const raw = fs.readFileSync(configPath, "utf8");
-      const parsed = JSON.parse(raw) as Config;
-      expect(parsed).toEqual(SAMPLE_CONFIG);
-    });
-
-    it("creates parent directory if it does not exist", () => {
-      const nestedPath = path.join(tmpDir, "nested", "dir", "config.json");
-      const manager = new ConfigManager(nestedPath);
-      manager.write(SAMPLE_CONFIG);
-
-      expect(fs.existsSync(nestedPath)).toBe(true);
-    });
-
-    it("overwrites existing config file", () => {
-      const manager = new ConfigManager(configPath);
-      manager.write(SAMPLE_CONFIG);
-
-      const updated = { ...SAMPLE_CONFIG, accessToken: "new-token" };
-      manager.write(updated);
-
-      const raw = fs.readFileSync(configPath, "utf8");
-      expect(JSON.parse(raw).accessToken).toBe("new-token");
-    });
-
-    it("removes the tmp file after successful rename", () => {
-      const manager = new ConfigManager(configPath);
-      manager.write(SAMPLE_CONFIG);
-
-      const tmpPath = `${configPath}.tmp`;
-      expect(fs.existsSync(tmpPath)).toBe(false);
-    });
-
-    it("sets 0600 permissions on POSIX", () => {
-      if (process.platform === "win32") return;
-
-      const manager = new ConfigManager(configPath);
-      manager.write(SAMPLE_CONFIG);
-
-      const stat = fs.statSync(configPath);
-      // eslint-disable-next-line no-bitwise
-      const mode = stat.mode & 0o777;
-      expect(mode).toBe(0o600);
-    });
-
-  });
-});

package/src/__tests__/defineTool.test.ts

@@ -1,223 +0,0 @@
-import { jest } from "@jest/globals";
-import { z } from "zod";
-
-import { defineTool } from "../defineTool.js";
-import { NexvoraApiError, NexvoraClient } from "../NexvoraClient.js";
-import { RateLimiterRegistry } from "../RateLimiter.js";
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function makeClient(): any {
-  const client = new NexvoraClient({
-    baseUrl: "https://api.nxvora.online",
-    accessToken: "token",
-    agentId: "00000000-0000-0000-0000-000000000002",
-  });
-  (client as any).sendAudit = jest.fn().mockResolvedValue(undefined);
-  return client;
-}
-
-describe("defineTool", () => {
-  const echoTool = {
-    name: "test_echo",
-    description: "Echo tool",
-    inputSchema: z.object({ message: z.string() }),
-    handler: async (input: { message: string }) => `echo: ${input.message}`,
-  };
-
-  it("returns text content on success", async () => {
-    const client = makeClient();
-    const handler = defineTool(echoTool, client);
-
-    const result = await handler({ message: "hello" });
-
-    expect(result.isError).toBeFalsy();
-    expect(result.content[0]?.text).toBe("echo: hello");
-  });
-
-  it("sends success audit on success", async () => {
-    const client = makeClient();
-    const handler = defineTool(echoTool, client);
-
-    await handler({ message: "hello" });
-
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ toolName: "test_echo", outcome: "success" }),
-    );
-  });
-
-  it("returns error content and sends error audit on validation failure", async () => {
-    const client = makeClient();
-    const handler = defineTool(echoTool, client);
-
-    const result = await handler({ message: 123 }); // wrong type
-
-    expect(result.isError).toBe(true);
-    expect(result.content[0]?.text).toContain("Invalid input");
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ toolName: "test_echo", outcome: "error", errorCode: "VALIDATION_ERROR" }),
-    );
-  });
-
-  it("sends rate_limited audit on 429 API error", async () => {
-    const client = makeClient();
-    const rateLimitedTool = {
-      ...echoTool,
-      handler: async () => {
-        throw new NexvoraApiError(429, "Too Many Requests", "/tasks");
-      },
-    };
-    const handler = defineTool(rateLimitedTool, client);
-
-    const result = await handler({ message: "test" });
-
-    expect(result.isError).toBe(true);
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ outcome: "rate_limited" }),
-    );
-  });
-
-  it("sends unauthorized audit on 401 API error", async () => {
-    const client = makeClient();
-    const unauthorizedTool = {
-      ...echoTool,
-      handler: async () => {
-        throw new NexvoraApiError(401, "Unauthorized", "/tasks");
-      },
-    };
-    const handler = defineTool(unauthorizedTool, client);
-
-    const result = await handler({ message: "test" });
-
-    expect(result.isError).toBe(true);
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ outcome: "unauthorized" }),
-    );
-  });
-
-  it("sends error audit on unexpected errors", async () => {
-    const client = makeClient();
-    const bugsyTool = {
-      ...echoTool,
-      handler: async () => {
-        throw new Error("Something exploded");
-      },
-    };
-    const handler = defineTool(bugsyTool, client);
-
-    const result = await handler({ message: "test" });
-
-    expect(result.isError).toBe(true);
-    expect(result.content[0]?.text).toContain("Something exploded");
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ outcome: "error", errorCode: "UNEXPECTED_ERROR" }),
-    );
-  });
-
-  it("includes agentId from client in audit payload", async () => {
-    const client = makeClient();
-    const handler = defineTool(echoTool, client);
-
-    await handler({ message: "test" });
-
-    expect(client.sendAudit).toHaveBeenCalledWith(
-      expect.objectContaining({ agentId: "00000000-0000-0000-0000-000000000002" }),
-    );
-  });
-
-  it("includes durationMs in success audit", async () => {
-    const client = makeClient();
-    const handler = defineTool(echoTool, client);
-
-    await handler({ message: "test" });
-
-    const auditCall = client.sendAudit.mock.calls[0][0];
-    expect(typeof auditCall.durationMs).toBe("number");
-    expect(auditCall.durationMs).toBeGreaterThanOrEqual(0);
-  });
-
-  describe("rate limiting", () => {
-    beforeEach(() => {
-      jest.useFakeTimers({ now: 1_000_000_000_000 });
-    });
-    afterEach(() => {
-      jest.useRealTimers();
-    });
-
-    it("allows calls when rate limiter has capacity", async () => {
-      const client = makeClient();
-      const rateLimiter = new RateLimiterRegistry({ test_echo: 10 });
-      const handler = defineTool(echoTool, client, rateLimiter);
-
-      const result = await handler({ message: "hello" });
-
-      expect(result.isError).toBeFalsy();
-      expect(result.content[0]?.text).toBe("echo: hello");
-    });
-
-    it("returns rate_limited error when bucket is exhausted", async () => {
-      const client = makeClient();
-      const rateLimiter = new RateLimiterRegistry({ test_echo: 1 });
-      const handler = defineTool(echoTool, client, rateLimiter);
-
-      await handler({ message: "first" }); // consumes the only token
-      const result = await handler({ message: "second" }); // should be blocked
-
-      expect(result.isError).toBe(true);
-      expect(result.content[0]?.text).toContain("Rate limit exceeded");
-      expect(result.content[0]?.text).toContain("test_echo");
-      expect(result.content[0]?.text).toContain("Retry after");
-    });
-
-    it("sends rate_limited audit when bucket is exhausted", async () => {
-      const client = makeClient();
-      const rateLimiter = new RateLimiterRegistry({ test_echo: 1 });
-      const handler = defineTool(echoTool, client, rateLimiter);
-
-      await handler({ message: "first" });
-      await handler({ message: "second" }); // blocked
-
-      // second call should have sent a rate_limited audit
-      const auditCalls = client.sendAudit.mock.calls as Array<[{ outcome: string }]>;
-      const rateLimitedAudit = auditCalls.find(([payload]) => payload.outcome === "rate_limited");
-      expect(rateLimitedAudit).toBeDefined();
-    });
-
-    it("does not invoke handler when rate limited", async () => {
-      const client = makeClient();
-      const rateLimiter = new RateLimiterRegistry({ test_echo: 1 });
-      const handlerSpy = jest.fn().mockResolvedValue("result") as jest.MockedFunction<
-        () => Promise<string>
-      >;
-      const spiedTool = { ...echoTool, handler: handlerSpy };
-      const handler = defineTool(spiedTool, client, rateLimiter);
-
-      await handler({ message: "first" }); // consumes token
-      await handler({ message: "second" }); // blocked
-
-      expect(handlerSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it("allows calls again after bucket refills", async () => {
-      const client = makeClient();
-      const rateLimiter = new RateLimiterRegistry({ test_echo: 1 }); // 1/min
-      const handler = defineTool(echoTool, client, rateLimiter);
-
-      await handler({ message: "first" }); // consume
-      const blocked = await handler({ message: "blocked" });
-      expect(blocked.isError).toBe(true);
-
-      jest.advanceTimersByTime(65_000); // advance past the 60s refill
-
-      const allowed = await handler({ message: "after refill" });
-      expect(allowed.isError).toBeFalsy();
-    });
-
-    it("proceeds normally with no rate limiter passed", async () => {
-      const client = makeClient();
-      const handler = defineTool(echoTool, client); // no rate limiter
-
-      const result = await handler({ message: "unlimited" });
-      expect(result.isError).toBeFalsy();
-    });
-  });
-});

package/src/__tests__/fixtures/config.json

@@ -1,7 +0,0 @@
-{
-  "accessToken": "int-test-access-token",
-  "refreshToken": "int-test-refresh-token",
-  "expiresAt": 9999999999,
-  "serverUrl": "https://api.nxvora.online",
-  "userId": "int-test-user-001"
-}