Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

14.3 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

// Importing the browser controller pulls in modules that open Redis clients.
vi.mock("ioredis", () => ({
  default: class {
    on() {
      return this;
    }
  },
}));
vi.mock("../services/rate-limiter", () => ({
  redisRateLimitClient: { pttl: vi.fn().mockResolvedValue(-1), on: vi.fn() },
}));
vi.mock("./keyless-prompt-analytics", () => ({
  trackKeylessPromptShown: vi.fn(),
}));
vi.mock("./keyless", async importOriginal => {
  const actual = await importOriginal<typeof import("./keyless")>();
  return { ...actual, checkKeylessEligibility: vi.fn() };
});

import { config } from "../config";
import { keylessEligibilityController } from "../controllers/v2/keyless-eligibility";
import { browserError } from "../controllers/v2/browser";
import { HangarError } from "./hangar";
import { BrowserSessionError } from "./browser-lifecycle";
import {
  KEYLESS_FREE_TIER_LIMIT_MESSAGE,
  checkKeylessEligibility,
  keylessLimitBody,
  keylessProviderToolsBody,
  keylessSignupUrlForIp,
  keylessTeamId,
  keylessTeamUuid,
  reportKeylessPromptShown,
} from "./keyless";
import { trackKeylessPromptShown } from "./keyless-prompt-analytics";
import { decryptKeylessSignupToken } from "./keyless-signup-link";
import { logger } from "./logger";
import { mintWorldIdCredential } from "./world-id";

const TEST_KEY = "AAECAwQFBgcICQoLDA0ODw==";
const IP = "203.0.113.8";
const TEAM_UUID = "abd15a03-d147-557e-801b-005da8c69bbf";

/** The prompt reported to analytics, with its defaults for IP. */
function shown(fields: Partial<Parameters<typeof trackKeylessPromptShown>[0]>) {
  return {
    keylessTeamId: TEAM_UUID,
    tokenLink: true,
    ...fields,
  };
}

/** The prompt a /k link carries, or null for any other link. */
function decoded(url: unknown) {
  const match = /^https:\/\/firecrawl\.dev\/k\/([0-9a-z]{12})$/.exec(
    String(url),
  );
  return match ? decryptKeylessSignupToken(match[1]) : null;
}

function fakeRes() {
  const res: any = {};
  res.status = vi.fn(() => res);
  res.json = vi.fn(() => res);
  return res;
}

const originalKeys = config.KEYLESS_SIGNUP_LINK_KEYS;
beforeEach(() => {
  config.KEYLESS_SIGNUP_LINK_KEYS = TEST_KEY;
  vi.spyOn(logger, "warn").mockImplementation(() => logger);
});

afterEach(() => {
  config.KEYLESS_SIGNUP_LINK_KEYS = originalKeys;
  vi.clearAllMocks();
  vi.restoreAllMocks();
});

describe("keylessTeamUuid", () => {
  it("matches the cross-repo vector in firecrawl-web lib/keyless-signup-link.test.ts", () => {
    expect(keylessTeamUuid(keylessTeamId(IP))).toBe(
      "abd15a03-d147-557e-801b-005da8c69bbf",
    );
  });
});

describe("keyless limit prompt", () => {
  it("keeps the internal marker message on the regular signup link", () => {
    expect(KEYLESS_FREE_TIER_LIMIT_MESSAGE).toContain(
      "create a free API key at https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api\n",
    );
  });

  it("puts the caller's own link in the credit-limit body and log", async () => {
    const body = await keylessLimitBody(
      "preview_keyless_203.0.113.8",
      "v2_search",
      { body: { integration: "cli" } },
    );

    expect(decoded(body.signup_url)).toEqual({
      ipv4: IP,
      surface: "cli",
      reason: "limit",
    });
    expect(body).toMatchObject({ success: false, reason: "credits" });
    expect(body.error).toContain(`${body.signup_url}\n`);
    expect(logger.warn).toHaveBeenCalledWith(
      "Keyless request blocked",
      expect.objectContaining({
        signupRef: body.signup_url.split("/k/")[1],
      }),
    );
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({ surface: "cli", reason: "limit", httpStatus: 429 }),
    );
  });

  it("uses the api surface when no request is given", async () => {
    const body = await keylessLimitBody(
      "preview_keyless_203.0.113.8",
      "v2_scrape",
    );
    expect(decoded(body.signup_url)?.surface).toBe("api");
  });

  it("gives the regular signup link when no key is configured", async () => {
    config.KEYLESS_SIGNUP_LINK_KEYS = undefined;
    const body = await keylessLimitBody(
      "preview_keyless_203.0.113.8",
      "v2_scrape",
      { body: { origin: "mcp-cursor@1" } },
    );
    expect(body.signup_url).toBe(
      "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp",
    );
    expect(body.error).toContain(`${body.signup_url}\n`);
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({
        surface: "mcp",
        reason: "limit",
        httpStatus: 429,
        tokenLink: false,
      }),
    );
  });

  it("keys IPv4-mapped IPv6 on the IPv4 identity and gives other IPs the regular link", () => {
    expect(
      decoded(keylessSignupUrlForIp("::ffff:203.0.113.8", "mcp", "limit").url),
    ).toEqual({ ipv4: IP, surface: "mcp", reason: "limit" });
    expect(keylessSignupUrlForIp("2001:db8::1", "mcp", "limit")).toEqual({
      url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp",
    });
    expect(keylessSignupUrlForIp("unknown", "api", "limit")).toEqual({
      url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
    });
  });
});

describe("keyless provider tools prompt", () => {
  it("puts the caller's own link in the refusal and reports it", () => {
    const body = keylessProviderToolsBody("preview_keyless_203.0.113.8", {
      body: { origin: "cli" },
    });

    expect(decoded(body.signup_url)).toEqual({
      ipv4: IP,
      surface: "cli",
      reason: "account_only_tool",
    });
    expect(body).toEqual({
      success: false,
      error: expect.stringMatching(
        /^An API key is required for provider tools\. /,
      ),
      signup_url: body.signup_url,
    });
    expect(body.error).toContain(`${body.signup_url}\n`);
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({ surface: "cli", reason: "account_only_tool", httpStatus: 403 }),
    );
  });

  it("gives a World ID caller the regular signup link and reports nothing", () => {
    const body = keylessProviderToolsBody(
      `preview_keyless_wid_${"h".repeat(43)}`,
      {
        body: {},
      },
    );

    expect(body.signup_url).toBe(
      "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
    );
    expect(body.error).toContain(`${body.signup_url}\n`);
    expect(trackKeylessPromptShown).not.toHaveBeenCalled();
  });
});

describe("reportKeylessPromptShown", () => {
  it("reports an IPv4-mapped IPv6 caller under the IPv4 team id", () => {
    reportKeylessPromptShown("::ffff:203.0.113.8", "api", "limit", 429, "ref");
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({ surface: "api", reason: "limit", httpStatus: 429 }),
    );
  });

  it.each([null, undefined, "", "unknown", "2001:db8::1"])(
    "does not report a caller without a keyless identity (%j)",
    ip => {
      reportKeylessPromptShown(ip, "api", "limit", 429);
      expect(trackKeylessPromptShown).not.toHaveBeenCalled();
    },
  );
});

describe("browserError", () => {
  it("replaces the keyless browser limit text with the caller's own link", () => {
    const res = fakeRes();
    browserError(
      res,
      new BrowserSessionError(429, KEYLESS_FREE_TIER_LIMIT_MESSAGE),
      {
        auth: { team_id: "preview_keyless_203.0.113.8" },
        body: { origin: "cli" },
        headers: {},
      } as any,
    );

    expect(res.status).toHaveBeenCalledWith(429);
    const body = res.json.mock.calls[0][0];
    expect(decoded(body.signup_url)).toEqual({
      ipv4: IP,
      surface: "cli",
      reason: "limit",
    });
    expect(body).toEqual({
      success: false,
      error: expect.stringContaining(`${body.signup_url}\n`),
      signup_url: body.signup_url,
    });
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({ surface: "cli", reason: "limit", httpStatus: 429 }),
    );
  });

  it("leaves other browser errors unchanged", () => {
    const res = fakeRes();
    browserError(res, new HangarError(409, "Session closed."), {
      auth: { team_id: "preview_keyless_203.0.113.8" },
    } as any);

    expect(res.status).toHaveBeenCalledWith(409);
    expect(res.json).toHaveBeenCalledWith({
      success: false,
      error: "Session closed.",
    });
    expect(trackKeylessPromptShown).not.toHaveBeenCalled();
  });
});

describe("keyless eligibility signup link", () => {
  const originalSecret = config.KEYLESS_PROXY_SECRET;
  beforeEach(() => {
    config.KEYLESS_PROXY_SECRET = "proxy-secret";
  });
  afterEach(() => {
    config.KEYLESS_PROXY_SECRET = originalSecret;
  });

  const eligibilityRequest = (query: Record<string, string> = {}, ip = IP) =>
    ({
      headers: {
        "x-firecrawl-keyless-secret": "proxy-secret",
        "x-firecrawl-keyless-ip": ip,
      },
      query,
    }) as any;

  const MCP_FALLBACK =
    "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp";

  it.each([
    ["requests", "limit"],
    ["credits", "limit"],
    ["suspicious", "suspicious_ip"],
  ] as const)(
    "links an identity refused for %s to its own mcp link tagged %s",
    async (refusal, reason) => {
      vi.mocked(checkKeylessEligibility).mockResolvedValue({
        eligible: false,
        reason: refusal,
      });
      const res = fakeRes();

      await keylessEligibilityController(eligibilityRequest(), res);

      // Refusals stay 200 so the MCP serves structured recovery, not a challenge.
      expect(res.status).toHaveBeenCalledWith(200);
      const body = res.json.mock.calls[0][0];
      expect(body).toEqual({
        eligible: false,
        reason: refusal,
        signupUrl: expect.any(String),
      });
      expect(decoded(body.signupUrl)).toEqual({
        ipv4: IP,
        surface: "mcp",
        reason,
      });
      // The MCP relays the link as the prompt, so the check reports it.
      expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
        shown({ surface: "mcp", reason, httpStatus: 200 }),
      );
    },
  );

  it("gives a suspicious refusal the regular mcp link when no key is configured", async () => {
    config.KEYLESS_SIGNUP_LINK_KEYS = undefined;
    vi.mocked(checkKeylessEligibility).mockResolvedValue({
      eligible: false,
      reason: "suspicious",
    });
    const res = fakeRes();

    await keylessEligibilityController(eligibilityRequest(), res);

    expect(res.json).toHaveBeenCalledWith({
      eligible: false,
      reason: "suspicious",
      signupUrl: MCP_FALLBACK,
    });
  });

  it.each(["disabled", "error"] as const)(
    "gives the regular signup link when the refusal is %s",
    async reason => {
      vi.mocked(checkKeylessEligibility).mockResolvedValue({
        eligible: false,
        reason,
      });
      const res = fakeRes();

      await keylessEligibilityController(eligibilityRequest(), res);

      expect(res.status).toHaveBeenCalledWith(200);
      expect(res.json).toHaveBeenCalledWith({
        eligible: false,
        reason,
        signupUrl: MCP_FALLBACK,
      });
      expect(trackKeylessPromptShown).not.toHaveBeenCalled();
    },
  );

  it("gives a non-IPv4 caller the regular signup link", async () => {
    vi.mocked(checkKeylessEligibility).mockResolvedValue({
      eligible: false,
      reason: "ineligible_ip",
    });
    const res = fakeRes();

    await keylessEligibilityController(
      eligibilityRequest({ signup_link: "1" }, "2001:db8::1"),
      res,
    );

    expect(res.json).toHaveBeenCalledWith({
      eligible: false,
      reason: "ineligible_ip",
      signupUrl: MCP_FALLBACK,
    });
    // An IPv6 caller is not a keyless identity, so nothing is reported.
    expect(trackKeylessPromptShown).not.toHaveBeenCalled();
  });

  it("checks a forwarded World ID credential only while World ID is configured", async () => {
    const original = {
      WORLD_ID_CLIENT_ID: config.WORLD_ID_CLIENT_ID,
      WORLD_ID_CLIENT_SECRET: config.WORLD_ID_CLIENT_SECRET,
      WORLD_ID_CREDENTIAL_SECRET: config.WORLD_ID_CREDENTIAL_SECRET,
      WORLD_ID_SUBJECT_SECRET: config.WORLD_ID_SUBJECT_SECRET,
    };
    try {
      config.WORLD_ID_CLIENT_ID = "app_test";
      config.WORLD_ID_CLIENT_SECRET = "client-secret";
      config.WORLD_ID_CREDENTIAL_SECRET = "c".repeat(32);
      config.WORLD_ID_SUBJECT_SECRET = "s".repeat(32);
      const hash = "h".repeat(43);
      const { credential } = mintWorldIdCredential(hash);
      vi.mocked(checkKeylessEligibility).mockResolvedValue({ eligible: true });
      const request = () => {
        const req = eligibilityRequest();
        req.headers["x-firecrawl-world-id"] = credential;
        return req;
      };

      await keylessEligibilityController(request(), fakeRes());
      await keylessEligibilityController(eligibilityRequest(), fakeRes());
      config.WORLD_ID_CLIENT_SECRET = undefined;
      await keylessEligibilityController(request(), fakeRes());

      expect(vi.mocked(checkKeylessEligibility).mock.calls).toEqual([
        [IP, `wid_${hash}`],
        [IP, undefined],
        [IP, undefined],
      ]);
    } finally {
      Object.assign(config, original);
    }
  });

  it("omits the link for an eligible IP unless asked", async () => {
    vi.mocked(checkKeylessEligibility).mockResolvedValue({ eligible: true });
    const res = fakeRes();

    await keylessEligibilityController(eligibilityRequest(), res);
    await keylessEligibilityController(
      eligibilityRequest({ signup_link: "1" }),
      res,
    );

    expect(res.status.mock.calls).toEqual([[200], [200]]);
    expect(res.json.mock.calls[0]).toEqual([{ eligible: true }]);
    // Only the asked-for account-only link is a prompt.
    expect(trackKeylessPromptShown).toHaveBeenCalledExactlyOnceWith(
      shown({ surface: "mcp", reason: "account_only_tool", httpStatus: 200 }),
    );
    const asked = res.json.mock.calls[1][0];
    expect(asked).toEqual({ eligible: true, signupUrl: expect.any(String) });
    expect(decoded(asked.signupUrl)).toEqual({
      ipv4: IP,
      surface: "mcp",
      reason: "account_only_tool",
    });
  });

  it("tags the account-only link with that reason even when the IP is also refused", async () => {
    vi.mocked(checkKeylessEligibility).mockResolvedValue({
      eligible: false,
      reason: "credits",
    });
    const res = fakeRes();

    await keylessEligibilityController(
      eligibilityRequest({ signup_link: "1" }),
      res,
    );

    expect(decoded(res.json.mock.calls[0][0].signupUrl)?.reason).toBe(
      "account_only_tool",
    );
  });
});