Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
14.4 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import { createHash } from "node:crypto";
import type { IncomingMessage, ServerResponse } from "node:http";
import { format } from "node:util";
import { Readable, Writable } from "node:stream";
import type { GfsVerifiedClaims } from "../auth/verify";
import type { AuthzContext } from "../authz/permissionClient";
import { GfsMetrics } from "../metrics";
import { RateLimiter } from "../quota/rateLimit";
import type { GfsResource } from "./read";
import { GfsServingHandler, type ServingDeps } from "./serve";

/**
 * The per-subject agent rate limit (#699): every request from a host principal
 * spends the read or the write budget right after subject resolution and before
 * authorization. User and linked-admin principals are never charged here:
 * control-api meters their Desktop requests, and the Control UI operator plane
 * (/api/v1/gfs/proxy) is not metered by either service yet (#762).
 */

class FakeRes extends Writable {
  statusCode = 0;
  headers: Record<string, string> = {};
  headersSent = false;
  private chunks: Buffer[] = [];
  writeHead(status: number, headers?: Record<string, string>): this {
    this.statusCode = status;
    this.headersSent = true;
    if (headers) Object.assign(this.headers, headers);
    return this;
  }
  setHeader(name: string, value: string): this {
    this.headers[name] = value;
    return this;
  }
  _write(chunk: Buffer | string, _enc: BufferEncoding, cb: (e?: Error | null) => void): void {
    this.chunks.push(Buffer.from(chunk));
    cb();
  }
  get body(): string {
    return Buffer.concat(this.chunks).toString("utf8");
  }
  get json(): { ok: boolean; error?: { code: string; message: string; limit?: string } } {
    return JSON.parse(this.body);
  }
}

const HOST_A = "host:1st:mcp-host/agent-a";
const HOST_B = "host:1st:mcp-host/agent-b";
const USER_ID = "11111111-1111-4111-8111-111111111111";
const ADMIN_ID = "22222222-2222-4222-8222-222222222222";
const DESKTOP_USER_ID = "33333333-3333-4333-8333-333333333333";
const RID = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
const REQUEST_ID = "44444444-4444-4444-8444-444444444444";

const DIR: GfsResource = {
  resourceId: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  drive: "main",
  parentResourceId: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  name: "docs",
  kind: "directory",
  pathCache: "/docs",
  version: 2,
  bytes: 0,
  blobKey: null,
  contentSha256: null,
  deletedAt: null,
  updatedAt: "2026-01-01T00:00:00.000Z",
};

function claimsFor(token: string): GfsVerifiedClaims {
  const base = { drive: "main", scopes: ["gfs.read", "gfs.write"] as GfsVerifiedClaims["scopes"], pathBindings: [], iat: 0, exp: 0 };
  if (token === "linked-admin") {
    return {
      ...base,
      sub: ADMIN_ID,
      principalType: "control-admin",
      brokeredAuthority: { desktopUserId: DESKTOP_USER_ID, controlAdminId: ADMIN_ID, authoritySource: "linked-admin" },
    };
  }
  return { ...base, sub: token };
}

function contextFor(claims: Pick<GfsVerifiedClaims, "sub" | "brokeredAuthority">): AuthzContext {
  if (claims.brokeredAuthority) {
    return {
      drive: "main",
      subjects: ["operator:"],
      isOperator: true,
      primarySubject: ADMIN_ID,
      effectiveControlAdminId: ADMIN_ID,
      desktopUserId: DESKTOP_USER_ID,
      authoritySource: "linked-admin",
    };
  }
  if (claims.sub.startsWith("host:")) {
    return { drive: "main", subjects: [claims.sub], isOperator: false, primarySubject: claims.sub };
  }
  return { drive: "main", subjects: [`user:${claims.sub}`], isOperator: false, primarySubject: claims.sub };
}

function harness(opts: { reads?: number; writes?: number; windowMs?: number; allowed?: boolean } = {}) {
  const clock = { t: 1_000_000 };
  const windowMs = opts.windowMs ?? 60_000;
  const rateLimit = {
    reads: new RateLimiter({ limit: opts.reads ?? 100, windowMs, now: () => clock.t }),
    writes: new RateLimiter({ limit: opts.writes ?? 100, windowMs, now: () => clock.t }),
  };
  const replaces: string[] = [];
  const listChildrenBySubject: string[] = [];
  const metrics = new GfsMetrics();
  let current = "";
  const listChildren = vi.fn(async () => {
    listChildrenBySubject.push(current);
    return [];
  });
  const writeService = {
    async replace(input: { mutation: { subject: string } }) {
      replaces.push(input.mutation.subject);
      return { ...DIR, kind: "file" as const, version: 3 };
    },
  } as unknown as ServingDeps["writeService"];
  const deps: ServingDeps = {
    verifyToken: (token) => {
      current = token;
      return claimsFor(token);
    },
    resolveContext: async (claims) => contextFor(claims),
    authorize: async () => ({ allowed: opts.allowed !== false }),
    audit: { record: async () => undefined },
    store: { getResource: async () => DIR, listChildren },
    blobs: { read: async () => Readable.from([]) },
    writeService,
    metrics,
    rateLimit,
    now: () => clock.t,
  };
  const handler = new GfsServingHandler(deps);

  async function get(token: string): Promise<FakeRes> {
    const res = new FakeRes();
    const request = { url: `/v1/resources/${RID}/children`, method: "GET", headers: { authorization: `Bearer ${token}` } };
    await handler.tryHandle(request as unknown as IncomingMessage, res as unknown as ServerResponse);
    return res;
  }

  async function put(token: string): Promise<FakeRes> {
    const res = new FakeRes();
    const stream = Readable.from([Buffer.from(JSON.stringify({ content: "hi", ifMatch: 2 }))]) as unknown as IncomingMessage;
    stream.url = `/v1/resources/${RID}/content`;
    stream.method = "PUT";
    stream.headers = { authorization: `Bearer ${token}`, "x-request-id": REQUEST_ID };
    await handler.tryHandle(stream, res as unknown as ServerResponse);
    return res;
  }

  return { clock, rateLimit, replaces, listChildren, listChildrenBySubject, metrics, get, put };
}

afterEach(() => {
  vi.restoreAllMocks();
});

describe("GfsServingHandler — per-subject agent rate limit", () => {
  it("case 1: caps an agent's writes and answers 429 with the retry headers", async () => {
    const h = harness({ writes: 2 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.put(HOST_A)).statusCode).toBe(200);
    expect((await h.put(HOST_A)).statusCode).toBe(200);
    const denied = await h.put(HOST_A);
    expect(denied.statusCode).toBe(429);
    expect(denied.json.error?.code).toBe("rate_limited");
    expect(denied.json.error?.limit).toBe("agent_writes");
    expect(denied.headers["Retry-After"]).toBe("60");
    expect(denied.headers["X-RateLimit-Limit"]).toBe("2");
    expect(denied.headers["X-GFS-RateLimit-Scope"]).toBe("agent_writes");
    // The denied attempt never reached the executor.
    expect(h.replaces).toHaveLength(2);
  });

  it("case 2: caps an agent's reads", async () => {
    const h = harness({ reads: 2 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    const denied = await h.get(HOST_A);
    expect(denied.statusCode).toBe(429);
    expect(denied.json.error?.code).toBe("rate_limited");
    expect(denied.headers["X-GFS-RateLimit-Scope"]).toBe("agent_reads");
    expect(denied.headers["X-RateLimit-Limit"]).toBe("2");
    expect(h.listChildren).toHaveBeenCalledTimes(2);
  });

  it("case 3: keeps separate read and write budgets, and the read budget stays finite", async () => {
    const h = harness({ reads: 2, writes: 1 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    const readsCheck = vi.spyOn(h.rateLimit.reads, "check");
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.put(HOST_A)).statusCode).toBe(200);
    expect((await h.put(HOST_A)).statusCode).toBe(429);
    // Exhausting the writes did not drain the reads...
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    // ...and the reads are still capped.
    const third = await h.get(HOST_A);
    expect(third.statusCode).toBe(429);
    expect(third.headers["X-GFS-RateLimit-Scope"]).toBe("agent_reads");
    expect(readsCheck).toHaveBeenCalledTimes(3);
  });

  it("case 4: charges every attempt, including one that authorization denies", async () => {
    const h = harness({ writes: 1, allowed: false });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    const first = await h.put(HOST_A);
    expect(first.statusCode).toBe(403);
    expect(first.json.error?.code).toBe("forbidden");
    const second = await h.put(HOST_A);
    expect(second.statusCode).toBe(429);
    expect(second.json.error?.code).toBe("rate_limited");
    expect(h.replaces).toHaveLength(0);
  });

  it("case 5: meters each agent subject independently", async () => {
    const h = harness({ reads: 1 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect((await h.get(HOST_B)).statusCode).toBe(200);
    expect(h.listChildrenBySubject).toEqual([HOST_A, HOST_B]);
  });

  it("case 6: restores the budget once the window has elapsed", async () => {
    const h = harness({ reads: 1, windowMs: 60_000 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect(h.listChildren).toHaveBeenCalledTimes(1);
    h.clock.t += 60_001;
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect(h.listChildren).toHaveBeenCalledTimes(2);
  });

  it("case 7: reports one denial as exactly one warning and one counter increment", async () => {
    const h = harness({ reads: 1 });
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect(warn).toHaveBeenCalledTimes(0);
    expect(h.metrics.snapshot().rateLimitDenied).toEqual({ read: 0, write: 0 });
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect(warn).toHaveBeenCalledTimes(1);
    expect(h.metrics.snapshot().rateLimitDenied).toEqual({ read: 1, write: 0 });
    expect(h.metrics.render()).toContain('gfs_rate_limit_denied_total{kind="read"} 1');
    expect(h.metrics.render()).toContain('gfs_rate_limit_denied_total{kind="write"} 0');
  });

  it("case 8: logs one line with a hashed subject and never the raw one", async () => {
    const h = harness({ writes: 1 });
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.put(HOST_A)).statusCode).toBe(200);
    const denied = await h.put(HOST_A);
    expect(denied.statusCode).toBe(429);
    expect(warn).toHaveBeenCalledTimes(1);
    const hashed = createHash("sha256").update(HOST_A).digest("hex");
    expect(warn.mock.calls[0]).toEqual([`[gfsc] rate_limit_denied kind=write subject=${hashed} suppressed=0`]);
    // console.warn renders its arguments with util.format; a log collector
    // splits records on newlines, so the rendered line must hold none.
    expect(format(...(warn.mock.calls[0] as unknown[]))).not.toContain("\n");
    expect(JSON.stringify(warn.mock.calls[0])).not.toContain(HOST_A);
    expect(JSON.stringify(warn.mock.calls[0])).not.toContain("agent-a");
    expect(denied.body).not.toContain(HOST_A);
    expect(denied.body).not.toContain("agent-a");
  });

  it("case 9: never charges user or linked-admin principals", async () => {
    const h = harness({ reads: 2 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    const readsCheck = vi.spyOn(h.rateLimit.reads, "check");
    for (let i = 0; i < 5; i += 1) {
      expect((await h.get(USER_ID)).statusCode).toBe(200);
      expect((await h.get("linked-admin")).statusCode).toBe(200);
    }
    expect(readsCheck).toHaveBeenCalledTimes(0);
    expect(h.listChildren).toHaveBeenCalledTimes(10);
    // The limiter is wired and live: a host subject is capped in the same test.
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect(readsCheck).toHaveBeenCalledTimes(3);
  });

  it("case 10: reports Retry-After from the oldest hit still in the window", async () => {
    const h = harness({ reads: 2, windowMs: 60_000 });
    vi.spyOn(console, "warn").mockImplementation(() => undefined);
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    h.clock.t += 20_000;
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    h.clock.t += 10_000;
    const denied = await h.get(HOST_A);
    expect(denied.statusCode).toBe(429);
    expect(denied.headers["Retry-After"]).toBe("30");
  });

  it("case 11: evicts subjects whose window has emptied", async () => {
    const h = harness({ reads: 5, windowMs: 60_000 });
    for (let i = 0; i < 50; i += 1) {
      expect((await h.get(`host:1st:mcp-host/agent-${i}`)).statusCode).toBe(200);
    }
    expect(h.rateLimit.reads.trackedSubjectCount).toBe(50);
    h.clock.t += 60_001;
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect(h.rateLimit.reads.trackedSubjectCount).toBe(1);
  });

  it("case 12: writes one denial line per subject per minute, counts every denial, and reports the suppressed lines", async () => {
    const h = harness({ reads: 1, windowMs: 60_000 });
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
    const hashed = createHash("sha256").update(HOST_A).digest("hex");
    expect((await h.get(HOST_A)).statusCode).toBe(200);

    const statuses: number[] = [];
    for (let i = 0; i < 50; i += 1) statuses.push((await h.get(HOST_A)).statusCode);
    // Witness: all 50 requests were denied, and the counter saw every one.
    expect(statuses).toEqual(Array.from({ length: 50 }, () => 429));
    expect(h.metrics.snapshot().rateLimitDenied).toEqual({ read: 50, write: 0 });
    expect(warn.mock.calls).toEqual([[`[gfsc] rate_limit_denied kind=read subject=${hashed} suppressed=0`]]);

    // One minute later the read budget is back: one request passes, the next is denied.
    h.clock.t += 60_000;
    expect((await h.get(HOST_A)).statusCode).toBe(200);
    expect((await h.get(HOST_A)).statusCode).toBe(429);
    expect(h.metrics.snapshot().rateLimitDenied).toEqual({ read: 51, write: 0 });
    expect(warn).toHaveBeenCalledTimes(2);
    expect(warn.mock.calls[1]).toEqual([`[gfsc] rate_limit_denied kind=read subject=${hashed} suppressed=49`]);
    expect(format(...(warn.mock.calls[1] as unknown[]))).not.toContain("\n");
  });
});