Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(api): link keyless prompts to opaque per-identity /k links (#4856)
Rakshith Ramprakash1b0904c84115
diff --git a/apps/api/.env.example b/apps/api/.env.exampleindex 490c8b69a..a5da41a9b 100644--- a/apps/api/.env.example+++ b/apps/api/.env.example@@ -24,6 +24,11 @@ MCP_ACTION_LOG_SECRET=# Shared only between the hosted MCP signer and Core verifier. Use 32+ random# characters and do not reuse KEYLESS_PROXY_SECRET.MCP_DELEGATED_CREDENTIAL_SECRET=+# Keyless signup link keys: comma-separated base64 16-byte AES keys+# (openssl rand -base64 16). The first encrypts the /k/<token> links in keyless+# prompts; all are tried to decrypt. Set the same value in firecrawl-web.+# Unset sends the regular signup link.+KEYLESS_SIGNUP_LINK_KEYS=# SearchApi key. Head to https://searchapi.com/ to get your API keySEARCHAPI_API_KEY=diff --git a/apps/api/src/__tests__/snips/v2/keyless.test.ts b/apps/api/src/__tests__/snips/v2/keyless.test.tsindex addb6b2ab..f7da83517 100644--- a/apps/api/src/__tests__/snips/v2/keyless.test.ts+++ b/apps/api/src/__tests__/snips/v2/keyless.test.ts@@ -13,6 +13,7 @@ import { db } from "../../../db/connection";import * as schema from "../../../db/schema";import { and, desc, eq, gt } from "drizzle-orm";import request from "supertest";+import { decryptKeylessSignupToken } from "../../../lib/keyless-signup-link";// The keyless tier is disabled unless both limits are configured. The harness// passes the shell env through to the server, so we read the same env here and@@ -40,10 +41,27 @@ async function flushKeylessBuckets() {}}-// Every keyless prompt links to signup with these tags so new accounts can be-// attributed to the keyless free tier.+// Every keyless prompt links to signup at firecrawl.dev/k/<token>, the+// encrypted prompt, or the regular signup link (utm_source=keyless plus the+// surface) when the server has no KEYLESS_SIGNUP_LINK_KEYS. The URL is always+// followed by whitespace, never punctuation.const KEYLESS_SIGNUP_URL =- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";+ /https:\/\/(firecrawl\.dev\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}|www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=(api|mcp|cli))(?=\s)/;+const KEYLESS_SIGNUP_URL_EXACT =+ /^https:\/\/(firecrawl\.dev\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}|www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=(api|mcp|cli))$/;++// The harness passes the shell env to the server, so the token can be checked+// here when a key is set; without one the server sends the regular link.+const SIGNUP_LINK_KEYS_SET = !!process.env.KEYLESS_SIGNUP_LINK_KEYS;++/** Surface and reason a /k link carries; null for the regular signup link. */+function signupLinkPrompt(url: unknown) {+ const token = String(url).split("/k/")[1];+ if (!token) return null;+ const prompt = decryptKeylessSignupToken(token);+ expect(prompt).not.toBeNull();+ return { surface: prompt!.surface, reason: prompt!.reason };+}// Recover the loopback IP the server keyed on, so we can seed its credit counter.async function currentKeylessIp(): Promise<string> {@@ -112,7 +130,15 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(response.body.error).toContain("not supported by the keyless free tier",);- expect(response.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(response.body.error).toMatch(KEYLESS_SIGNUP_URL);+ expect(response.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);+ expect(response.body.error).toContain(response.body.signup_url);+ if (SIGNUP_LINK_KEYS_SET) {+ expect(signupLinkPrompt(response.body.signup_url)).toEqual({+ surface: "api",+ reason: "unsupported_endpoint",+ });+ }expect(response.body.error).toContain("Authorization: Bearer YOUR_API_KEY");});@@ -163,13 +189,57 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);- expect(blocked.body.error).not.toContain(`${KEYLESS_SIGNUP_URL}.`);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");// Out of quota β emit the OAuth-discovery header so agents find the key flow.expect(blocked.headers["www-authenticate"]).toContain("resource_metadata");});+ it("gives an identity the same signup link on every prompt, and a separate one per surface (429)", async () => {+ await request(TEST_API_URL)+ .post("/v2/scrape")+ .set("Content-Type", "application/json")+ .send({ origin: "mcp" });+ const ip = await currentKeylessIp();+ await redisRateLimitClient.set(+ `keyless_credits:${ip}`,+ String(KEYLESS_CREDITS_PER_DAY),+ );++ const blockedAs = (body: Record<string, unknown>) =>+ request(TEST_API_URL)+ .post("/v2/scrape")+ .set("Content-Type", "application/json")+ .send(body);+ const mcpFirst = await blockedAs({ origin: "[email protected]" });+ const mcpSecond = await blockedAs({ origin: "[email protected]" });+ const cli = await blockedAs({ integration: "cli" });++ for (const blocked of [mcpFirst, mcpSecond, cli]) {+ expect(blocked.statusCode).toBe(429);+ expect(blocked.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);+ expect(blocked.body.error).toContain(blocked.body.signup_url);+ // A /k link shows nothing about the caller or the surface.+ if (String(blocked.body.signup_url).includes("/k/")) {+ expect(blocked.body.signup_url).not.toContain("utm_");+ }+ expect(blocked.body.signup_url).not.toContain(ip);+ }+ expect(mcpSecond.body.signup_url).toBe(mcpFirst.body.signup_url);++ if (SIGNUP_LINK_KEYS_SET) {+ expect(cli.body.signup_url).not.toBe(mcpFirst.body.signup_url);+ expect(signupLinkPrompt(mcpFirst.body.signup_url)).toEqual({+ surface: "mcp",+ reason: "limit",+ });+ expect(signupLinkPrompt(cli.body.signup_url)).toEqual({+ surface: "cli",+ reason: "limit",+ });+ }+ });+it("enforces the daily credit cap with the credit signup message (429)", async () => {// Materialize the loopback IP, then seed its credit counter to the cap.await request(TEST_API_URL)@@ -189,7 +259,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");});@@ -218,7 +288,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");});@@ -261,7 +331,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.reason).toBe("credits");expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -306,7 +376,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.reason).toBe("credits");expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -348,7 +418,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -478,7 +548,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -517,7 +587,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -568,7 +638,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {.send({ origin: "mcp" });expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -691,7 +761,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {expect(blocked.statusCode).toBe(429);expect(blocked.body.error).toContain("keyless free tier rate limit");- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY",);@@ -811,7 +881,15 @@ describeIf(SPUR_ENABLED)("Keyless free tier β Spur IP reputation", () => {expect(response.statusCode).toBe(403);expect(response.body.success).toBe(false);expect(response.body.error).toContain("suspicious");- expect(response.body.error).toContain(KEYLESS_SIGNUP_URL);+ expect(response.body.error).toMatch(KEYLESS_SIGNUP_URL);+ expect(response.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);+ if (SIGNUP_LINK_KEYS_SET) {+ // Relayed with the proxy secret, so the prompt reached the user via MCP.+ expect(signupLinkPrompt(response.body.signup_url)).toEqual({+ surface: "mcp",+ reason: "suspicious_ip",+ });+ }// Out of the keyless path β emit the OAuth-discovery header.expect(response.headers["www-authenticate"]).toContain("resource_metadata",diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 1e96563eb..6d1376b55 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -110,6 +110,22 @@ const configSchema = z.object({// existing privacy-controlled conversion pipeline. Never use the proxy or// credential secrets here: this value is only an analytics pseudonymizer.KEYLESS_CONVERSION_HMAC_SECRET: emptyStringAsUndefined(z.string().min(32)),+ // AES-128 keys for keyless signup link tokens (firecrawl.dev/k/<token>):+ // comma-separated base64, 16 bytes each. The first encrypts; every key is+ // tried to decrypt, so keep a rotated-out key listed while its links live.+ // Must match firecrawl-web's KEYLESS_SIGNUP_LINK_KEYS. Unset sends the+ // regular signup link.+ KEYLESS_SIGNUP_LINK_KEYS: emptyStringAsUndefined(+ z+ .string()+ .refine(+ value =>+ value+ .split(",")+ .every(key => /^[A-Za-z0-9+/]{21}[AQgw]==$/.test(key.trim())),+ "KEYLESS_SIGNUP_LINK_KEYS must be comma-separated base64 16-byte keys",+ ),+ ),// Dedicated signer/verifier secret for short-lived MCP delegated credentials.// Keep separate from KEYLESS_PROXY_SECRET because delegated credentials can// authorize billed requests for a managed OAuth connection.diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.tsindex 647a43b84..775e93ca7 100644--- a/apps/api/src/controllers/__tests__/auth.test.ts+++ b/apps/api/src/controllers/__tests__/auth.test.ts@@ -19,6 +19,7 @@ import {isKeylessConfigured,keylessConversionCohort,} from "../../lib/keyless";+import { decryptKeylessSignupToken } from "../../lib/keyless-signup-link";import { logger } from "../../lib/logger";import { isKeylessIpSuspicious } from "../../lib/spur";import { db } from "../../db/connection";@@ -108,6 +109,7 @@ describe("authenticateUser", () => {const originalIntrospectSecret = config.OAUTH_INTROSPECT_SECRET;const originalPreviewToken = config.PREVIEW_TOKEN;const originalAgentInteropSecret = config.AGENT_INTEROP_SECRET;+ const originalKeylessSignupLinkKeys = config.KEYLESS_SIGNUP_LINK_KEYS;beforeEach(() => {vi.mocked(isKeylessConfigured).mockReturnValue(false);@@ -127,6 +129,7 @@ describe("authenticateUser", () => {config.OAUTH_INTROSPECT_SECRET = originalIntrospectSecret;config.PREVIEW_TOKEN = originalPreviewToken;config.AGENT_INTEROP_SECRET = originalAgentInteropSecret;+ config.KEYLESS_SIGNUP_LINK_KEYS = originalKeylessSignupLinkKeys;vi.unstubAllGlobals();vi.clearAllMocks();});@@ -214,8 +217,17 @@ describe("authenticateUser", () => {);});- it("links every keyless signup prompt to the keyless-tagged signup URL", async () => {+ // The prompt a /k link carries, or null for any other link.+ const decodedLink = (url: unknown) => {+ const match = /^https:\/\/firecrawl\.dev\/k\/([0-9a-z]{12})$/.exec(+ String(url),+ );+ return match ? decryptKeylessSignupToken(match[1]) : null;+ };++ it("links every keyless prompt to the caller's own token, tagged with the prompt reason", async () => {config.USE_DB_AUTHENTICATION = true;+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";vi.mocked(isKeylessConfigured).mockReturnValue(true);vi.mocked(consumeKeylessRequest).mockResolvedValue({ok: false,@@ -223,13 +235,11 @@ describe("authenticateUser", () => {requestsUsed: 1,creditsUsed: 100,});- vi.spyOn(logger, "warn").mockImplementation(() => logger);+ const warn = vi.spyOn(logger, "warn").mockImplementation(() => logger);const keylessRequest = () => ({headers: {},- socket: { remoteAddress: "203.0.113.8" },+ socket: { remoteAddress: "::ffff:203.0.113.8" },});- const taggedSignupUrl =- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";const limited = await authenticateUser(keylessRequest(),@@ -251,30 +261,164 @@ describe("authenticateUser", () => {{ allowKeyless: true },);- // A period right after the URL would be copied into utm_medium.- expect(limited).toEqual(- expect.objectContaining({- error: expect.not.stringContaining(`${taggedSignupUrl}.`),- }),- );- for (const [auth, status] of [- [limited, 429],- [unsupported, 401],- [suspicious, 403],+ for (const [auth, status, reason] of [+ [limited, 429, "limit"],+ [unsupported, 401, "unsupported_endpoint"],+ [suspicious, 403, "suspicious_ip"],] as const) {+ const signupUrl = (auth as { signupUrl?: string }).signupUrl;+ expect(decodedLink(signupUrl)).toEqual({+ ipv4: "203.0.113.8",+ surface: "api",+ reason,+ });expect(auth).toEqual(expect.objectContaining({success: false,status,- // Nothing follows the URL's query, so a dropped utm_content stays out.- error: expect.stringMatching(- /https:\/\/www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=api(?![&\w])/,+ // The URL is followed by whitespace, never punctuation.+ error: expect.stringContaining(+ `${signupUrl}${status === 429 ? "\n" : " "}`,),}),);+ // Nothing about the surface or the identity is visible in the link.+ expect(signupUrl).not.toContain("utm_");+ expect((auth as { error: string }).error).not.toContain("203.0.113.8");+ }+ for (const [message, auth] of [+ ["Keyless request blocked", limited],+ ["Keyless request blocked: suspicious IP", suspicious],+ ] as const) {+ expect(warn).toHaveBeenCalledWith(+ message,+ expect.objectContaining({+ signupRef: (auth as { signupUrl: string }).signupUrl.split("/k/")[1],+ }),+ );}});+ it.each([+ [{ integration: "cli" }, {}, "cli"],+ [{ origin: "[email protected]" }, {}, "mcp"],+ [{}, { "x-origin": "cli" }, "cli"],+ [{ origin: "[email protected]" }, {}, "api"],+ ] as const)(+ "tags the keyless limit link for body %j headers %j with the %s surface",+ async (body, headers, surface) => {+ config.USE_DB_AUTHENTICATION = true;+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";+ vi.mocked(isKeylessConfigured).mockReturnValue(true);+ vi.mocked(consumeKeylessRequest).mockResolvedValue({+ ok: false,+ reason: "requests",+ requestsUsed: 11,+ creditsUsed: 0,+ });+ vi.spyOn(logger, "warn").mockImplementation(() => logger);++ const auth = await authenticateUser(+ { body, headers, socket: { remoteAddress: "203.0.113.8" } },+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(decodedLink((auth as { signupUrl?: string }).signupUrl)).toEqual({+ ipv4: "203.0.113.8",+ surface,+ reason: "limit",+ });+ },+ );++ it("keys the hosted MCP's link on the forwarded end-user IP and the mcp surface", async () => {+ config.USE_DB_AUTHENTICATION = true;+ config.KEYLESS_PROXY_SECRET = "proxy-secret";+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";+ vi.mocked(isKeylessConfigured).mockReturnValue(true);+ vi.mocked(consumeKeylessRequest).mockResolvedValue({+ ok: false,+ reason: "credits",+ requestsUsed: 1,+ creditsUsed: 100,+ });+ vi.spyOn(logger, "warn").mockImplementation(() => logger);++ const auth = await authenticateUser(+ {+ body: { origin: "api" },+ headers: {+ "x-firecrawl-keyless-secret": "proxy-secret",+ "x-firecrawl-keyless-ip": "198.51.100.7",+ },+ socket: { remoteAddress: "10.0.0.1" },+ },+ {},+ RateLimiterMode.Search,+ { allowKeyless: true },+ );++ expect(decodedLink((auth as { signupUrl?: string }).signupUrl)).toEqual({+ ipv4: "198.51.100.7",+ surface: "mcp",+ reason: "limit",+ });+ });++ it("falls back to the regular signup link and still returns the 429 when no key is configured", async () => {+ config.USE_DB_AUTHENTICATION = true;+ config.KEYLESS_SIGNUP_LINK_KEYS = undefined;+ vi.mocked(isKeylessConfigured).mockReturnValue(true);+ vi.mocked(consumeKeylessRequest).mockResolvedValue({+ ok: false,+ reason: "credits",+ requestsUsed: 1,+ creditsUsed: 100,+ });+ vi.spyOn(logger, "warn").mockImplementation(() => logger);++ const auth = await authenticateUser(+ { headers: {}, socket: { remoteAddress: "203.0.113.8" } },+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(auth).toEqual(+ expect.objectContaining({+ status: 429,+ signupUrl:+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",+ error: expect.stringContaining(+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api\n",+ ),+ }),+ );+ });++ it("gives a non-IPv4 caller on an unsupported endpoint the regular signup link", async () => {+ config.USE_DB_AUTHENTICATION = true;+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";+ vi.mocked(isKeylessConfigured).mockReturnValue(true);++ const auth = await authenticateUser(+ { headers: {}, socket: { remoteAddress: "2001:db8::1" } },+ {},+ RateLimiterMode.Crawl,+ { allowKeyless: false },+ );++ expect(auth).toEqual(+ expect.objectContaining({+ status: 401,+ signupUrl:+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",+ }),+ );+ });+it("writes normal API-key ACUC entries to the general-purpose cache", async () => {config.USE_DB_AUTHENTICATION = true;vi.mocked(getValue).mockResolvedValue(null);diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.tsindex 61591cfc4..f9be80525 100644--- a/apps/api/src/controllers/auth.ts+++ b/apps/api/src/controllers/auth.ts@@ -13,15 +13,16 @@ import {} from "../services/rate-limiter";import { isTrustedAgentInteropRequest } from "../lib/agent-interop";import {- KEYLESS_FREE_TIER_LIMIT_MESSAGE,- KEYLESS_SIGNUP_URL,consumeKeylessRequest,isKeylessConfigured,keylessExhaustionTelemetry,isKeylessIpEligible,+ keylessLimitPrompt,+ keylessSignupUrlForIp,keylessTeamId,normalizeKeylessIpv4,} from "../lib/keyless";+import { keylessSignupSurface } from "../lib/keyless-signup-link";import { isKeylessIpSuspicious } from "../lib/spur";import { keylessAuthTotal } from "../lib/keyless-metrics";import { checkIpRestriction } from "../lib/ip-restriction";@@ -464,12 +465,38 @@ export async function clearACUCTeam(team_id: string): Promise<void> {await deleteKey(`acuc_team_${team_id}`);}-const KEYLESS_ENDPOINT_NOT_AVAILABLE_MESSAGE = `This endpoint is not supported by the keyless free tier. Sign up for a free API key at ${KEYLESS_SIGNUP_URL} for more endpoints, more usage, and higher rate limits.+// Both prompts end the sentence after the URL with a space, so a copied link+// never picks up the period.+function keylessEndpointNotAvailableMessage(signupUrl: string): string {+ return `This endpoint is not supported by the keyless free tier. Sign up for a free API key at ${signupUrl} for more endpoints, more usage, and higher rate limits.Then authenticate with:Authorization: Bearer YOUR_API_KEY`;+}-const KEYLESS_SUSPICIOUS_IP_MESSAGE = `Unfortunately, your IP address looks suspicious, so Firecrawl can't be used without an API key from here. Sign up for a free API key at ${KEYLESS_SIGNUP_URL} for 1000 credits and higher rate limits for free. (If you're an agent, you can also use https://firecrawl.dev/auth.md)`;+function keylessSuspiciousIpMessage(signupUrl: string): string {+ return `Unfortunately, your IP address looks suspicious, so Firecrawl can't be used without an API key from here. Sign up for a free API key at ${signupUrl} for 1000 credits and higher rate limits for free. (If you're an agent, you can also use https://firecrawl.dev/auth.md)`;+}++/**+ * The real client IP for keyless. A trusted proxy (e.g. the hosted MCP) may+ * forward the end-user's IP via x-firecrawl-keyless-ip, authenticated with a+ * shared secret β without the secret the header is ignored, so direct callers+ * can't spoof their IP to dodge the per-IP cap.+ */+function keylessClientIp(req): string {+ let ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";+ if (+ config.KEYLESS_PROXY_SECRET &&+ req.headers["x-firecrawl-keyless-secret"] === config.KEYLESS_PROXY_SECRET+ ) {+ const forwarded = req.headers["x-firecrawl-keyless-ip"];+ if (typeof forwarded === "string" && forwarded.trim()) {+ ip = forwarded.trim();+ }+ }+ return ip;+}/*** Keyless free tier: official MCP/CLI/SDK clients can call scrape, search, and@@ -497,10 +524,16 @@ async function handleKeylessAuth(// Configured, but this endpoint isn't part of the keyless tier: tell the user// they need a key (with the signup nudge) rather than a bare "Unauthorized".if (!allowKeyless) {+ const { url } = keylessSignupUrlForIp(+ keylessClientIp(req),+ keylessSignupSurface(req),+ "unsupported_endpoint",+ );return {success: false,- error: KEYLESS_ENDPOINT_NOT_AVAILABLE_MESSAGE,+ error: keylessEndpointNotAvailableMessage(url),status: 401,+ signupUrl: url,};}@@ -508,22 +541,11 @@ async function handleKeylessAuth(const integration = req.body?.integration;// No origin/surface gate: any request without an API key may use the free// tier on the allowlisted endpoints (the API itself is free). origin and- // integration are still recorded below for abuse monitoring.+ // integration are still recorded below for abuse monitoring, and pick the+ // surface of the signup link.+ const signupSurface = keylessSignupSurface(req);- // Key on the real client IP. A trusted proxy (e.g. the hosted MCP) may- // forward the end-user's IP via x-firecrawl-keyless-ip, authenticated with a- // shared secret β without the secret the header is ignored, so direct callers- // can't spoof their IP to dodge the per-IP cap.- let ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";- if (- config.KEYLESS_PROXY_SECRET &&- req.headers["x-firecrawl-keyless-secret"] === config.KEYLESS_PROXY_SECRET- ) {- const forwarded = req.headers["x-firecrawl-keyless-ip"];- if (typeof forwarded === "string" && forwarded.trim()) {- ip = forwarded.trim();- }- }+ let ip = keylessClientIp(req);// Only a valid IPv4 identity gets keyless: IPv6 is too cheap to rotate for a// per-IP cap to mean anything, and malformed/forwarded values must not be@@ -540,6 +562,11 @@ async function handleKeylessAuth(// runs before consuming quota so a flagged IP doesn't burn a request slot.if (await isKeylessIpSuspicious(ip)) {keylessAuthTotal.inc({ mode, outcome: "suspicious" });+ const { url, signupRef } = keylessSignupUrlForIp(+ ip,+ signupSurface,+ "suspicious_ip",+ );logger.warn("Keyless request blocked: suspicious IP", {canonicalLog: "keyless/consume",ip,@@ -547,13 +574,15 @@ async function handleKeylessAuth(integration: req.body?.integration,blocked: true,reason: "suspicious",+ ...(signupRef ? { signupRef } : {}),});return {success: false,- error: KEYLESS_SUSPICIOUS_IP_MESSAGE,+ error: keylessSuspiciousIpMessage(url),status: 403,// Tell agents where to find the key/signup flow they now need.agentAuthDiscovery: true,+ signupUrl: url,};}@@ -599,18 +628,21 @@ async function handleKeylessAuth(if (!result.ok) {keylessAuthTotal.inc({ mode, outcome: result.reason ?? "error" });+ const prompt = keylessLimitPrompt(ip, signupSurface);logger.warn("Keyless request blocked", {...baseLog,blocked: true,event: "keyless_exhausted",reason: result.reason,retryAfterSeconds: result.retryAfterSeconds,+ ...(prompt.signupRef ? { signupRef: prompt.signupRef } : {}),...keylessExhaustionTelemetry(ip),});return {success: false,- error: KEYLESS_FREE_TIER_LIMIT_MESSAGE,+ error: prompt.error,status: 429,+ signupUrl: prompt.signup_url,// Direct API callers receive discovery metadata; MCP maps this in-band.agentAuthDiscovery: true,keylessReason: result.reason,diff --git a/apps/api/src/controllers/v1/scrape.ts b/apps/api/src/controllers/v1/scrape.tsindex 8e4d30d77..fdbb51132 100644--- a/apps/api/src/controllers/v1/scrape.ts+++ b/apps/api/src/controllers/v1/scrape.ts@@ -225,7 +225,7 @@ async function scrapeControllerInner(applyAgentAuthDiscoveryHeader(res);return res.status(429)- .json(await keylessLimitBody(req.auth.team_id, "v1_scrape"));+ .json(await keylessLimitBody(req.auth.team_id, "v1_scrape", req));}reservedKeylessCredits = projectedKeylessCredits;}diff --git a/apps/api/src/controllers/v1/search.ts b/apps/api/src/controllers/v1/search.tsindex ed079cd2c..88ba299d0 100644--- a/apps/api/src/controllers/v1/search.ts+++ b/apps/api/src/controllers/v1/search.ts@@ -264,7 +264,7 @@ export async function searchController(applyAgentAuthDiscoveryHeader(res);return res.status(429)- .json(await keylessLimitBody(req.auth.team_id, "v1_search"));+ .json(await keylessLimitBody(req.auth.team_id, "v1_search", req));}reservedKeylessCredits = projectedKeylessCredits;}diff --git a/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts b/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.tsindex fb4abcb1a..c08625173 100644--- a/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts+++ b/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts@@ -143,7 +143,12 @@ describe("developer category code_searches ledger", () => {await searchController(req, res);expect(res.status).toHaveBeenCalledWith(429);- expect(mockKeylessLimitBody).toHaveBeenCalledWith(TEAM_ID, "v2_search");+ // The request picks the utm_medium of the caller's signup link.+ expect(mockKeylessLimitBody).toHaveBeenCalledWith(+ TEAM_ID,+ "v2_search",+ req,+ );expect(res.json).toHaveBeenCalledWith({success: false,error: "keyless limit reached",diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.tsindex fbec5fad5..ee1fb71cd 100644--- a/apps/api/src/controllers/v2/browser.ts+++ b/apps/api/src/controllers/v2/browser.ts@@ -5,6 +5,10 @@ import {import { deleteBrowserProfile } from "../../lib/browser-sessions";import { deleteHangarProfile } from "../../lib/hangar";import { Response } from "express";+import {+ KEYLESS_FREE_TIER_LIMIT_MESSAGE,+ keylessLimitPromptForTeam,+} from "../../lib/keyless";import { z } from "zod";import { config } from "../../config";import { RequestWithAuth } from "./types";@@ -64,7 +68,25 @@ const browserExecuteRequestSchema = z.object({origin: z.string().optional(),});-export function browserError(res: Response, error: unknown) {+export function browserError(+ res: Response,+ error: unknown,+ req?: RequestWithAuth<any, any, any>,+) {+ // Keyless browser budget exhaustion: give the caller its own signup link.+ if (+ req &&+ error instanceof HangarError &&+ error.status === 429 &&+ error.message === KEYLESS_FREE_TIER_LIMIT_MESSAGE+ ) {+ const prompt = keylessLimitPromptForTeam(req.auth.team_id, req);+ return res.status(429).json({+ success: false,+ error: prompt.error,+ signup_url: prompt.signup_url,+ });+ }return res.status(error instanceof HangarError ? error.status : 502).json({success: false,error:@@ -107,7 +129,7 @@ export async function browserCreateController(expiresAt,});} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -165,7 +187,7 @@ export async function browserExecuteController(: {}),});} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -203,7 +225,7 @@ export async function browserProfileDeleteController("A session is currently saving to this profile. Stop that session, then delete the profile.",});}- return browserError(res, error);+ return browserError(res, error, req);}}@@ -216,7 +238,7 @@ export async function browserDeleteController(try {return res.json(await stopBrowserSession(session));} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -238,7 +260,7 @@ export async function browserStatusController(error: browser.error ?? undefined,});} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -290,7 +312,7 @@ export async function browserReplayController(pageCount: 1,});} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -310,6 +332,6 @@ export async function browserReplayPageController(res.setHeader("Cache-Control", "no-store");return res.status(200).send(recording.playlist);} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}diff --git a/apps/api/src/controllers/v2/keyless-eligibility.ts b/apps/api/src/controllers/v2/keyless-eligibility.tsindex b9eee6cfb..49f5f7f0b 100644--- a/apps/api/src/controllers/v2/keyless-eligibility.ts+++ b/apps/api/src/controllers/v2/keyless-eligibility.ts@@ -1,6 +1,14 @@import { Request, Response } from "express";import { config } from "../../config";-import { checkKeylessEligibility } from "../../lib/keyless";+import {+ checkKeylessEligibility,+ keylessSignupUrlForIp,+} from "../../lib/keyless";+import {+ type KeylessPromptReason,+ keylessFallbackSignupUrl,+ keylessSignupSurface,+} from "../../lib/keyless-signup-link";/*** Internal endpoint for trusted proxies (the hosted MCP) to check, before a@@ -8,6 +16,11 @@ import { checkKeylessEligibility } from "../../lib/keyless";* consuming quota. Gated by the shared KEYLESS_PROXY_SECRET; the client IP is* supplied via x-firecrawl-keyless-ip. Lets the MCP serve keyless when eligible* and return a structured recovery action when the IP is not eligible.+ *+ * An ineligible result carries `signupUrl`, the caller's own signup link, which+ * the MCP relays in its recovery message. `?signup_link=1` asks for the link on+ * any result, for the account-only tool prompt (a tool keyless sessions cannot+ * use), and tags it with that reason whatever the eligibility.*/export async function keylessEligibilityController(req: Request,@@ -24,5 +37,23 @@ export async function keylessEligibilityController((typeof ipHeader === "string" ? ipHeader.trim() : "") || req.ip || "";const result = await checkKeylessEligibility(ip);- res.status(200).json(result);+ const accountOnlyTool = req.query?.signup_link === "1";+ if (result.eligible && !accountOnlyTool) {+ res.status(200).json(result);+ return;+ }+ const surface = keylessSignupSurface(req);+ const reason: KeylessPromptReason | undefined = accountOnlyTool+ ? "account_only_tool"+ : result.reason === "requests" || result.reason === "credits"+ ? "limit"+ : result.reason === "suspicious"+ ? "suspicious_ip"+ : undefined;+ // A tier that is off or a limiter that is down is not a prompt about this+ // identity, so it gets the regular signup link.+ const signupUrl = reason+ ? keylessSignupUrlForIp(ip, surface, reason).url+ : keylessFallbackSignupUrl(surface);+ res.status(200).json({ ...result, signupUrl });}diff --git a/apps/api/src/controllers/v2/parse.ts b/apps/api/src/controllers/v2/parse.tsindex c70846f03..9d0b563f7 100644--- a/apps/api/src/controllers/v2/parse.ts+++ b/apps/api/src/controllers/v2/parse.ts@@ -414,7 +414,7 @@ export async function parseController(applyAgentAuthDiscoveryHeader(res);return res.status(429)- .json(await keylessLimitBody(req.auth.team_id, "v2_parse"));+ .json(await keylessLimitBody(req.auth.team_id, "v2_parse", req));}reservedKeylessCredits = projectedKeylessCredits;}diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.tsindex ffd67d8fb..be49a1e34 100644--- a/apps/api/src/controllers/v2/scrape-browser.ts+++ b/apps/api/src/controllers/v2/scrape-browser.ts@@ -258,10 +258,9 @@ export async function scrapeInteractController(profile,);if (created.error === true) {- if (- created.status === 429 &&- created.body.error === KEYLESS_FREE_TIER_LIMIT_MESSAGE- ) {+ // A keyless limit body carries the caller's own link, so match on it+ // rather than on the message text.+ if (created.status === 429 && "signup_url" in created.body) {applyAgentAuthDiscoveryHeader(res);}return res.status(created.status).json(created.body);@@ -331,7 +330,7 @@ export async function scrapeInteractController(try {await reserveBrowserPromptCredits(req, session);} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}try {@@ -445,7 +444,7 @@ export async function scrapeStopInteractiveBrowserController(try {return res.json(await stopBrowserSession(session));} catch (error) {- return browserError(res, error);+ return browserError(res, error, req);}}@@ -487,7 +486,7 @@ async function createSessionForScrape(: "Failed to create browser session.";const body =message === KEYLESS_FREE_TIER_LIMIT_MESSAGE- ? await keylessLimitBody(req.auth.team_id, "v2_browser")+ ? await keylessLimitBody(req.auth.team_id, "v2_browser", req): { success: false as const, error: message };return { error: true as const, status, body };}diff --git a/apps/api/src/controllers/v2/scrape.ts b/apps/api/src/controllers/v2/scrape.tsindex 3884b47f7..03cd81884 100644--- a/apps/api/src/controllers/v2/scrape.ts+++ b/apps/api/src/controllers/v2/scrape.ts@@ -268,7 +268,7 @@ export async function scrapeController(applyAgentAuthDiscoveryHeader(res);return res.status(429)- .json(await keylessLimitBody(req.auth.team_id, "v2_scrape"));+ .json(await keylessLimitBody(req.auth.team_id, "v2_scrape", req));}reservedKeylessCredits = projectedKeylessCredits;}diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.tsindex 656d6e6c3..22e385d5e 100644--- a/apps/api/src/controllers/v2/search.ts+++ b/apps/api/src/controllers/v2/search.ts@@ -385,7 +385,7 @@ async function searchControllerInner(applyAgentAuthDiscoveryHeader(res);return res.status(429)- .json(await keylessLimitBody(req.auth.team_id, "v2_search"));+ .json(await keylessLimitBody(req.auth.team_id, "v2_search", req));}reservedKeylessCredits = projectedKeylessCredits;}diff --git a/apps/api/src/lib/keyless-signup-link.test.ts b/apps/api/src/lib/keyless-signup-link.test.tsnew file mode 100644index 000000000..24a4dbfbc--- /dev/null+++ b/apps/api/src/lib/keyless-signup-link.test.ts@@ -0,0 +1,254 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { config } from "../config";+import { logger } from "./logger";+import {+ type KeylessPromptReason,+ type KeylessSignupSurface,+ decryptKeylessSignupToken,+ encryptKeylessSignupToken,+ ff1Decrypt,+ ff1Encrypt,+ keylessFallbackSignupUrl,+ keylessSignupLink,+ keylessSignupSurface,+} from "./keyless-signup-link";++// Shared with firecrawl-web lib/keyless-signup-link.test.ts: both repos must+// produce and accept exactly this token for this key and payload.+const CROSS_REPO_KEY = "AAECAwQFBgcICQoLDA0ODw==";+const CROSS_REPO_PAYLOAD = {+ ipv4: "203.0.113.8",+ surface: "mcp",+ reason: "limit",+} as const;+const CROSS_REPO_TOKEN = "hrxch5c20tcs";++const KEY = Buffer.from(CROSS_REPO_KEY, "base64");+const OTHER_KEY = Buffer.alloc(16, 7);+const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";++describe("FF1 (NIST SP 800-38G AES-128 samples)", () => {+ const key = Buffer.from("2B7E151628AED2A6ABF7158809CF4F3C", "hex");+ const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";+ const toNumerals = (s: string) => [...s].map(c => alphabet.indexOf(c));+ const fromNumerals = (n: number[]) => n.map(d => alphabet[d]).join("");++ it.each([+ ["sample 1", 10, "", "0123456789", "2433477484"],+ ["sample 2", 10, "39383736353433323130", "0123456789", "6124200773"],+ [+ "sample 3",+ 36,+ "3737373770717273373737",+ "0123456789abcdefghi",+ "a9tv40mll9kdu509eum",+ ],+ ] as const)("%s", (_name, radix, tweakHex, plaintext, ciphertext) => {+ const tweak = Buffer.from(tweakHex, "hex");+ expect(+ fromNumerals(ff1Encrypt(key, tweak, radix, toNumerals(plaintext))),+ ).toBe(ciphertext);+ expect(+ fromNumerals(ff1Decrypt(key, tweak, radix, toNumerals(ciphertext))),+ ).toBe(plaintext);+ });+});++describe("keyless signup token", () => {+ it("matches the cross-repo vector", () => {+ expect(encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, KEY)).toBe(+ CROSS_REPO_TOKEN,+ );+ expect(decryptKeylessSignupToken(CROSS_REPO_TOKEN, [KEY])).toEqual(+ CROSS_REPO_PAYLOAD,+ );+ });++ const surfaces: KeylessSignupSurface[] = ["api", "mcp", "cli"];+ const reasons: KeylessPromptReason[] = [+ "limit",+ "account_only_tool",+ "unsupported_endpoint",+ "suspicious_ip",+ ];+ it.each(+ surfaces.flatMap(surface => reasons.map(reason => [surface, reason])),+ )("round-trips surface %s and reason %s", (surface, reason) => {+ for (const ipv4 of ["0.0.0.0", "203.0.113.8", "255.255.255.255"]) {+ const payload = {+ ipv4,+ surface: surface as KeylessSignupSurface,+ reason: reason as KeylessPromptReason,+ };+ const token = encryptKeylessSignupToken(payload, KEY);+ expect(token).toMatch(/^[0-9abcdefghjkmnpqrstvwxyz]{12}$/);+ expect(decryptKeylessSignupToken(token!, [KEY])).toEqual(payload);+ }+ });++ it("rejects every single-character change to a token", () => {+ for (let i = 0; i < CROSS_REPO_TOKEN.length; i++) {+ for (const c of TOKEN_ALPHABET) {+ if (c === CROSS_REPO_TOKEN[i]) continue;+ const tampered =+ CROSS_REPO_TOKEN.slice(0, i) + c + CROSS_REPO_TOKEN.slice(i + 1);+ expect(decryptKeylessSignupToken(tampered, [KEY])).toBeNull();+ }+ }+ });++ it.each([+ "",+ "hrxch5c20tc",+ "hrxch5c20tcss",+ "HRXCH5C20TCS",+ "hrxch5c20tci",+ "hrxch5c20tc/",+ ])("rejects the malformed token %j", token => {+ expect(decryptKeylessSignupToken(token, [KEY])).toBeNull();+ });++ it("decrypts a token from a rotated-out key while it stays listed", () => {+ const oldToken = encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, OTHER_KEY)!;+ expect(decryptKeylessSignupToken(oldToken, [KEY])).toBeNull();+ expect(decryptKeylessSignupToken(oldToken, [KEY, OTHER_KEY])).toEqual(+ CROSS_REPO_PAYLOAD,+ );+ expect(+ decryptKeylessSignupToken(CROSS_REPO_TOKEN, [KEY, OTHER_KEY]),+ ).toEqual(CROSS_REPO_PAYLOAD);+ });++ it("shows no IP bytes in the clear", () => {+ // The unencrypted numerals of the IP, and the IP in hex or decimal.+ const ipNumerals = (+ (((203n << 24n) | (0n << 16n) | (113n << 8n) | 8n) << 28n) >>+ 25n+ )+ .toString(32)+ .padStart(7, "0");+ const token = encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, KEY)!;+ expect(token.slice(0, 7)).not.toBe(ipNumerals);+ for (const clear of ["cb007108", "203", "113", "cb", "71"]) {+ expect(token).not.toContain(clear);+ }+ // Neighbouring IPs give unrelated tokens.+ const next = encryptKeylessSignupToken(+ { ...CROSS_REPO_PAYLOAD, ipv4: "203.0.113.9" },+ KEY,+ )!;+ const shared = [...token].filter((c, i) => next[i] === c).length;+ expect(shared).toBeLessThan(6);+ });++ it("gives no token for a non-IPv4 identity", () => {+ for (const ipv4 of ["2001:db8::1", "::ffff:203.0.113.8", "unknown", ""]) {+ expect(+ encryptKeylessSignupToken({ ...CROSS_REPO_PAYLOAD, ipv4 }, KEY),+ ).toBeUndefined();+ }+ });+});++describe("keylessSignupLink", () => {+ const originalKeys = config.KEYLESS_SIGNUP_LINK_KEYS;+ beforeEach(() => {+ config.KEYLESS_SIGNUP_LINK_KEYS = CROSS_REPO_KEY;+ });+ afterEach(() => {+ config.KEYLESS_SIGNUP_LINK_KEYS = originalKeys;+ });++ it("builds a clean /k/<token> link with no query string", () => {+ expect(keylessSignupLink("203.0.113.8", "mcp", "limit")).toEqual({+ url: `https://firecrawl.dev/k/${CROSS_REPO_TOKEN}`,+ signupRef: CROSS_REPO_TOKEN,+ });+ });++ it("encrypts with the first key and decrypts with any listed key", () => {+ config.KEYLESS_SIGNUP_LINK_KEYS = `${OTHER_KEY.toString("base64")}, ${CROSS_REPO_KEY}`;+ const { signupRef } = keylessSignupLink("203.0.113.8", "mcp", "limit");+ expect(signupRef).not.toBe(CROSS_REPO_TOKEN);+ expect(decryptKeylessSignupToken(signupRef!, [OTHER_KEY])).toEqual(+ CROSS_REPO_PAYLOAD,+ );+ expect(decryptKeylessSignupToken(CROSS_REPO_TOKEN)).toEqual(+ CROSS_REPO_PAYLOAD,+ );+ });++ it.each([undefined, "", "not-a-key", "AAECAwQFBgcICQoLDA0O"])(+ "gives the regular signup link when the keys are %j",+ keys => {+ const warn = vi.spyOn(logger, "warn");+ config.KEYLESS_SIGNUP_LINK_KEYS = keys;+ expect(keylessSignupLink("203.0.113.8", "cli", "limit")).toEqual({+ url: keylessFallbackSignupUrl("cli"),+ });+ // A missing key is a plain fallback, not a caught failure.+ expect(warn).not.toHaveBeenCalled();+ warn.mockRestore();+ },+ );++ it.each([null, undefined, "", "2001:db8::1", "unknown"])(+ "gives the regular signup link for the non-IPv4 identity %j",+ ip => {+ expect(keylessSignupLink(ip, "api", "unsupported_endpoint")).toEqual({+ url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",+ });+ },+ );+});++describe("keylessSignupSurface", () => {+ const originalSecret = config.KEYLESS_PROXY_SECRET;+ afterEach(() => {+ config.KEYLESS_PROXY_SECRET = originalSecret;+ });++ it.each([+ [{ body: { integration: "cli" } }, "cli"],+ [{ body: { origin: "cli" } }, "cli"],+ [{ body: {}, headers: { "x-origin": "cli" } }, "cli"],+ [{ body: { origin: "[email protected]" } }, "mcp"],+ [{ body: {}, headers: { "x-origin": "[email protected]" } }, "mcp"],+ [{ body: { origin: "api" } }, "api"],+ [{ body: { origin: "[email protected]" } }, "api"],+ [{ body: { origin: "website" } }, "api"],+ [{ body: {} }, "api"],+ [{}, "api"],+ // Case-insensitive, like the warehouse classifier.+ [{ body: { origin: "CLI" } }, "cli"],+ [{ body: { integration: "Cli" } }, "cli"],+ [{ body: { origin: "[email protected]" } }, "mcp"],+ [{ body: {}, headers: { "x-origin": "[email protected]" } }, "mcp"],+ // v1 schemas prefault a missing origin to "api"; the header still counts.+ [{ body: { origin: "api" }, headers: { "x-origin": "cli" } }, "cli"],+ [{ body: { origin: "api" }, headers: { "x-origin": "mcp-x@1" } }, "mcp"],+ // An explicit non-default body origin still wins over the header.+ [+ { body: { origin: "[email protected]" }, headers: { "x-origin": "cli" } },+ "api",+ ],+ ] as const)("classifies %j as %s", (req, surface) => {+ expect(keylessSignupSurface(req as never)).toBe(surface);+ });++ it("treats a request relayed with the proxy secret as MCP", () => {+ config.KEYLESS_PROXY_SECRET = "proxy-secret";+ expect(+ keylessSignupSurface({+ body: { origin: "api" },+ headers: { "x-firecrawl-keyless-secret": "proxy-secret" },+ }),+ ).toBe("mcp");+ expect(+ keylessSignupSurface({+ body: { origin: "api" },+ headers: { "x-firecrawl-keyless-secret": "wrong" },+ }),+ ).toBe("api");+ });+});diff --git a/apps/api/src/lib/keyless-signup-link.ts b/apps/api/src/lib/keyless-signup-link.tsnew file mode 100644index 000000000..1913c87fe--- /dev/null+++ b/apps/api/src/lib/keyless-signup-link.ts@@ -0,0 +1,353 @@+import { createCipheriv } from "node:crypto";+import { isIPv4 } from "node:net";+import { config } from "../config";+import { logger } from "./logger";++// Keyless prompts link to signup at https://firecrawl.dev/k/<token>. The token+// is the prompt itself, encrypted: nothing is stored per identity, and the web+// app decrypts it at signup to join the account to the keyless ledger.+//+// Token format. Keep identical to firecrawl-web lib/keyless-signup-link.ts.+// Plaintext: a 60-bit integer, most significant bits first:+// bits 59..28 keyless IPv4 address (a.b.c.d as a big-endian uint32)+// bits 27..26 surface: 0 api, 1 mcp, 2 cli (3 reserved)+// bits 25..23 prompt reason: 0 limit, 1 account_only_tool,+// 2 unsupported_endpoint, 3 suspicious_ip (4..7 reserved)+// bits 22..0 check: always zero+// Written as 12 radix-32 numerals (5 bits each, most significant first) and+// encrypted with NIST SP 800-38G FF1 over AES-128, radix 32, tweak the ASCII+// bytes "fc-keyless-v1". The 12 output numerals are spelled in lowercase+// Crockford base32 (0123456789abcdefghjkmnpqrstvwxyz).+// A token is valid only if the 23 check bits decrypt to zero, so a forged or+// mistyped token passes with odds of about 1 in 8.4 million per key.+// Reserved surface or reason codes decode to null (a newer issuer).+//+// Keys: KEYLESS_SIGNUP_LINK_KEYS, comma-separated base64 16-byte AES keys. The+// first encrypts; decryption tries each in turn, so a rotated-out key keeps its+// links working while it stays in the list.+const KEYLESS_SIGNUP_LINK_BASE = "https://firecrawl.dev/k";++export type KeylessSignupSurface = "api" | "mcp" | "cli";++export type KeylessPromptReason =+ | "limit"+ | "account_only_tool"+ | "unsupported_endpoint"+ | "suspicious_ip";++// Index = code in the token. Append only.+const SURFACE_CODES: readonly KeylessSignupSurface[] = ["api", "mcp", "cli"];+const REASON_CODES: readonly KeylessPromptReason[] = [+ "limit",+ "account_only_tool",+ "unsupported_endpoint",+ "suspicious_ip",+];++const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";+const TOKEN_LENGTH = 12;+const TOKEN_PATTERN = /^[0-9abcdefghjkmnpqrstvwxyz]{12}$/;+const TOKEN_TWEAK = Buffer.from("fc-keyless-v1", "ascii");+const CHECK_BITS = 23n;+const CHECK_MASK = (1n << CHECK_BITS) - 1n;++/**+ * The regular signup link, used whenever no token can be given (no key+ * configured, or no IPv4 identity). It still tags the signup keyless with its+ * surface through the UTMs the web app already reads, so only the per-identity+ * join is lost, not the attribution.+ */+export function keylessFallbackSignupUrl(+ surface: KeylessSignupSurface,+): string {+ return `https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=${surface}`;+}++// ---------------------------------------------------------------------------+// FF1 (NIST SP 800-38G) with AES-128. Numeral strings are arrays of digits in+// [0, radix), most significant first.++function aesBlock(key: Buffer, block: Buffer): Buffer {+ const cipher = createCipheriv("aes-128-ecb", key, null);+ cipher.setAutoPadding(false);+ return Buffer.concat([cipher.update(block), cipher.final()]);+}++// PRF of the spec: AES CBC-MAC with a zero IV over a whole number of blocks.+function prf(key: Buffer, data: Buffer): Buffer {+ const cipher = createCipheriv("aes-128-cbc", key, Buffer.alloc(16));+ cipher.setAutoPadding(false);+ const out = Buffer.concat([cipher.update(data), cipher.final()]);+ return out.subarray(out.length - 16);+}++function numeralsToBigInt(numerals: number[], radix: number): bigint {+ const r = BigInt(radix);+ let x = 0n;+ for (const digit of numerals) x = x * r + BigInt(digit);+ return x;+}++function bigIntToNumerals(x: bigint, radix: number, length: number): number[] {+ const r = BigInt(radix);+ const out = new Array<number>(length);+ for (let i = length - 1; i >= 0; i--) {+ out[i] = Number(x % r);+ x /= r;+ }+ return out;+}++function bigIntToBytes(x: bigint, length: number): Buffer {+ const out = Buffer.alloc(length);+ for (let i = length - 1; i >= 0; i--) {+ out[i] = Number(x & 0xffn);+ x >>= 8n;+ }+ return out;+}++function ff1(+ key: Buffer,+ tweak: Buffer,+ radix: number,+ input: number[],+ encrypt: boolean,+): number[] {+ const n = input.length;+ if (key.length !== 16) throw new Error("FF1 needs a 16-byte AES-128 key");+ if (radix < 2 || radix > 65536 || n < 2) throw new Error("Bad FF1 domain");+ if (input.some(d => !Number.isInteger(d) || d < 0 || d >= radix)) {+ throw new Error("Numeral out of range");+ }+ const u = Math.floor(n / 2);+ const v = n - u;+ let A = input.slice(0, u);+ let B = input.slice(u);+ // b = ceil(ceil(v * log2(radix)) / 8), computed exactly.+ const b = Math.ceil((BigInt(radix) ** BigInt(v) - 1n).toString(2).length / 8);+ const d = 4 * Math.ceil(b / 4) + 4;+ const t = tweak.length;+ const P = Buffer.alloc(16);+ P.set([1, 2, 1], 0);+ P.writeUIntBE(radix, 3, 3);+ P[6] = 10;+ P[7] = u % 256;+ P.writeUInt32BE(n, 8);+ P.writeUInt32BE(t, 12);+ const pad = (((-t - b - 1) % 16) + 16) % 16;+ const extraBlocks = Math.ceil(d / 16) - 1;++ for (let round = 0; round < 10; round++) {+ const i = encrypt ? round : 9 - round;+ const Q = Buffer.concat([+ tweak,+ Buffer.alloc(pad),+ Buffer.from([i]),+ bigIntToBytes(numeralsToBigInt(encrypt ? B : A, radix), b),+ ]);+ const R = prf(key, Buffer.concat([P, Q]));+ const blocks = [R];+ for (let j = 1; j <= extraBlocks; j++) {+ const counter = bigIntToBytes(BigInt(j), 16);+ blocks.push(aesBlock(key, Buffer.from(R.map((x, k) => x ^ counter[k]))));+ }+ const y = BigInt(+ "0x" + Buffer.concat(blocks).subarray(0, d).toString("hex"),+ );+ const m = i % 2 === 0 ? u : v;+ const modulus = BigInt(radix) ** BigInt(m);+ if (encrypt) {+ const c = (numeralsToBigInt(A, radix) + y) % modulus;+ A = B;+ B = bigIntToNumerals(c, radix, m);+ } else {+ const c =+ (((numeralsToBigInt(B, radix) - y) % modulus) + modulus) % modulus;+ B = A;+ A = bigIntToNumerals(c, radix, m);+ }+ }+ return [...A, ...B];+}++export function ff1Encrypt(+ key: Buffer,+ tweak: Buffer,+ radix: number,+ numerals: number[],+): number[] {+ return ff1(key, tweak, radix, numerals, true);+}++export function ff1Decrypt(+ key: Buffer,+ tweak: Buffer,+ radix: number,+ numerals: number[],+): number[] {+ return ff1(key, tweak, radix, numerals, false);+}++// ---------------------------------------------------------------------------+// Token encode/decode.++type KeylessSignupPayload = {+ ipv4: string;+ surface: KeylessSignupSurface | null;+ reason: KeylessPromptReason | null;+};++// Canonical base64 of exactly 16 bytes.+const KEY_PATTERN = /^[A-Za-z0-9+/]{21}[AQgw]==$/;+let cachedKeys: { raw: string | undefined; keys: Buffer[] } | undefined;++/** Parsed KEYLESS_SIGNUP_LINK_KEYS; malformed entries are skipped. */+function signupLinkKeys(): Buffer[] {+ const raw = config.KEYLESS_SIGNUP_LINK_KEYS;+ if (cachedKeys && cachedKeys.raw === raw) return cachedKeys.keys;+ const keys = (raw ?? "")+ .split(",")+ .map(entry => entry.trim())+ .filter(entry => KEY_PATTERN.test(entry))+ .map(entry => Buffer.from(entry, "base64"));+ cachedKeys = { raw, keys };+ return keys;+}++/** The 12-character token for a prompt, or undefined for a non-IPv4 identity. */+export function encryptKeylessSignupToken(+ payload: {+ ipv4: string;+ surface: KeylessSignupSurface;+ reason: KeylessPromptReason;+ },+ key: Buffer,+): string | undefined {+ if (!isIPv4(payload.ipv4)) return undefined;+ const ip = payload.ipv4+ .split(".")+ .reduce((acc, octet) => (acc << 8n) | BigInt(Number(octet)), 0n);+ const plaintext =+ (ip << 28n) |+ (BigInt(SURFACE_CODES.indexOf(payload.surface)) << 26n) |+ (BigInt(REASON_CODES.indexOf(payload.reason)) << CHECK_BITS);+ return ff1Encrypt(+ key,+ TOKEN_TWEAK,+ 32,+ bigIntToNumerals(plaintext, 32, TOKEN_LENGTH),+ )+ .map(d => TOKEN_ALPHABET[d])+ .join("");+}++/**+ * The prompt a token carries, or null when it is malformed or no key yields+ * zero check bits. Tries every configured key unless keys are given.+ */+export function decryptKeylessSignupToken(+ token: string,+ keys: Buffer[] = signupLinkKeys(),+): KeylessSignupPayload | null {+ if (!TOKEN_PATTERN.test(token)) return null;+ const numerals = [...token].map(c => TOKEN_ALPHABET.indexOf(c));+ for (const key of keys) {+ const plaintext = numeralsToBigInt(+ ff1Decrypt(key, TOKEN_TWEAK, 32, numerals),+ 32,+ );+ if ((plaintext & CHECK_MASK) !== 0n) continue;+ const ip = Number(plaintext >> 28n);+ return {+ ipv4: [24, 16, 8, 0].map(shift => (ip >>> shift) & 255).join("."),+ surface: SURFACE_CODES[Number((plaintext >> 26n) & 3n)] ?? null,+ reason: REASON_CODES[Number((plaintext >> CHECK_BITS) & 7n)] ?? null,+ };+ }+ return null;+}++/**+ * The caller's own signup link for a prompt: firecrawl.dev/k/<token> for an+ * IPv4 identity when a key is configured, else the regular signup link. Pure+ * CPU, no I/O, never throws. `signupRef` is the token, for logs.+ */+export function keylessSignupLink(+ ipv4: string | null | undefined,+ surface: KeylessSignupSurface,+ reason: KeylessPromptReason,+): { url: string; signupRef?: string } {+ try {+ const key = signupLinkKeys()[0];+ const token =+ ipv4 && key+ ? encryptKeylessSignupToken({ ipv4, surface, reason }, key)+ : undefined;+ if (token) {+ return { url: `${KEYLESS_SIGNUP_LINK_BASE}/${token}`, signupRef: token };+ }+ } catch (error) {+ logger.warn("Keyless signup link encryption failed", {+ module: "keyless-signup-link",+ surface,+ error,+ });+ }+ return { url: keylessFallbackSignupUrl(surface) };+}++// ---------------------------------------------------------------------------+// Surface classification.++type RequestLike = {+ body?: unknown;+ headers?: Record<string, string | string[] | undefined>;+};++function lowerString(value: unknown): string | undefined {+ return typeof value === "string" ? value.trim().toLowerCase() : undefined;+}++function firstHeader(req: RequestLike, name: string): string | undefined {+ const value = req.headers?.[name];+ if (Array.isArray(value)) return value[0];+ return typeof value === "string" ? value : undefined;+}++/**+ * Surface of a keyless prompt, from the same signals as the warehouse+ * `usage_source`: CLI when origin or integration is `cli`, MCP when origin+ * starts with `mcp` or the hosted MCP relayed the request with the proxy+ * secret. Everything else, including requests with no origin, is `api`: the+ * prompt reached the caller as a raw API response, which is what+ * utm_medium=api meant before.+ */+export function keylessSignupSurface(req: RequestLike): KeylessSignupSurface {+ const body =+ req.body && typeof req.body === "object"+ ? (req.body as Record<string, unknown>)+ : {};+ // v1 schemas prefault a missing body origin to "api", which would mask an+ // x-origin header, so a bare "api" defers to the header. Classification is+ // case-insensitive, like the warehouse's.+ const bodyOrigin = lowerString(body.origin);+ const headerOrigin = lowerString(firstHeader(req, "x-origin"));+ const origin =+ bodyOrigin && bodyOrigin !== "api"+ ? bodyOrigin+ : (headerOrigin ?? bodyOrigin);+ const integration =+ lowerString(body.integration) ??+ lowerString(firstHeader(req, "x-integration"));+ if (+ config.KEYLESS_PROXY_SECRET &&+ firstHeader(req, "x-firecrawl-keyless-secret") ===+ config.KEYLESS_PROXY_SECRET+ ) {+ return "mcp";+ }+ if (integration === "cli" || origin === "cli") return "cli";+ if (origin?.startsWith("mcp")) return "mcp";+ return "api";+}diff --git a/apps/api/src/lib/keyless.signup-prompt.test.ts b/apps/api/src/lib/keyless.signup-prompt.test.tsnew file mode 100644index 000000000..a373e80bd--- /dev/null+++ b/apps/api/src/lib/keyless.signup-prompt.test.ts@@ -0,0 +1,317 @@+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: { ttl: vi.fn().mockResolvedValue(-1), on: 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 {+ KEYLESS_FREE_TIER_LIMIT_MESSAGE,+ checkKeylessEligibility,+ keylessLimitBody,+ keylessSignupUrlForIp,+ keylessTeamId,+ keylessTeamUuid,+} from "./keyless";+import { decryptKeylessSignupToken } from "./keyless-signup-link";+import { logger } from "./logger";++const TEST_KEY = "AAECAwQFBgcICQoLDA0ODw==";+const IP = "203.0.113.8";++/** 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],+ }),+ );+ });++ 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`);+ });++ 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("browserError", () => {+ it("replaces the keyless browser limit text with the caller's own link", () => {+ const res = fakeRes();+ browserError(res, new HangarError(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,+ });+ });++ 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.",+ });+ });+});++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,+ });+ },+ );++ 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,+ });+ },+ );++ 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,+ });+ });++ 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 }]);+ 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",+ );+ });+});diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.tsindex bc619786a..8c79df4f4 100644--- a/apps/api/src/lib/keyless.ts+++ b/apps/api/src/lib/keyless.ts@@ -11,6 +11,13 @@ import {keylessCreditBlocksTotal,keylessCreditsTotal,} from "./keyless-metrics";+import {+ type KeylessPromptReason,+ type KeylessSignupSurface,+ keylessFallbackSignupUrl,+ keylessSignupLink,+ keylessSignupSurface,+} from "./keyless-signup-link";// Keyless free tier: scrape, search, and interact can be used without an API key// from the official MCP server, CLI, or SDKs. It's gated per-IP/day by TWO@@ -23,17 +30,21 @@ import {const KEYLESS_REQUESTS_PER_DAY = config.KEYLESS_REQUESTS_PER_DAY;const KEYLESS_CREDITS_PER_DAY = config.KEYLESS_CREDITS_PER_DAY;-// Signup link for every keyless prompt. The UTM tags attribute the new account-// to the keyless free tier; the CLI swaps utm_medium to `cli` before printing.-export const KEYLESS_SIGNUP_URL =- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";--// Shared 429 copy for both keyless request-cap and credit-cap failures. The URL-// ends the sentence without a period so a copied link keeps a clean utm_medium.-export const KEYLESS_FREE_TIER_LIMIT_MESSAGE = `You've hit Firecrawl's keyless free tier rate limit. To continue now, create a free API key at ${KEYLESS_SIGNUP_URL}+// Keyless prompts link to signup at firecrawl.dev/k/<token>, where <token>+// is the encrypted prompt (see keyless-signup-link.ts). The constant uses the+// regular signup link and stays the marker for internal equality checks;+// responses swap in the caller's own link where they leave the API. The URL+// ends its line, so a copied link never picks up punctuation.+function keylessFreeTierLimitMessage(signupUrl: string): string {+ return `You've hit Firecrawl's keyless free tier rate limit. To continue now, create a free API key at ${signupUrl}Then authenticate with:Authorization: Bearer YOUR_API_KEY`;+}++export const KEYLESS_FREE_TIER_LIMIT_MESSAGE = keylessFreeTierLimitMessage(+ keylessFallbackSignupUrl("api"),+);// The tier is "configured" when BOTH limits are set β even to 0. Unset means the// feature is off (callers get a plain Unauthorized); 0 means it's on but the@@ -156,14 +167,56 @@ async function retryAfterSecondsFor(key: string): Promise<number | undefined> {}}+/**+ * Signup link for a keyless prompt: the caller's own /k/<token> link for a+ * valid IPv4 identity, the regular signup link for anything else.+ */+export function keylessSignupUrlForIp(+ ip: string | null | undefined,+ surface: KeylessSignupSurface,+ reason: KeylessPromptReason,+): { url: string; signupRef?: string } {+ return keylessSignupLink(+ ip && isKeylessIpEligible(ip) ? normalizeKeylessIpv4(ip) : null,+ surface,+ reason,+ );+}++/** The caller's own signup link and the limit message that carries it. */+export function keylessLimitPrompt(+ ip: string | null | undefined,+ surface: KeylessSignupSurface,+): { error: string; signup_url: string; signupRef?: string } {+ const { url, signupRef } = keylessSignupUrlForIp(ip, surface, "limit");+ return {+ error: keylessFreeTierLimitMessage(url),+ signup_url: url,+ ...(signupRef ? { signupRef } : {}),+ };+}++/** keylessLimitPrompt for a keyless team id; the regular signup link for other teams. */+export function keylessLimitPromptForTeam(+ teamId: string,+ req: Parameters<typeof keylessSignupSurface>[0],+): ReturnType<typeof keylessLimitPrompt> {+ return keylessLimitPrompt(+ keylessIpFromTeamId(teamId),+ keylessSignupSurface(req),+ );+}+/** Structured response for projected-credit reservation exhaustion. */export async function keylessLimitBody(teamId: string,mode: string,+ req?: Parameters<typeof keylessSignupSurface>[0],): Promise<{success: false;error: string;reason: "credits";+ signup_url: string;retry_after_seconds?: number;}> {const ip = keylessIpFromTeamId(teamId);@@ -176,6 +229,10 @@ export async function keylessLimitBody(// The reservation already proved the limit; missing TTL must not turn its// controlled 429 into a server error.}+ const prompt = keylessLimitPrompt(+ ip,+ req ? keylessSignupSurface(req) : "api",+ );logger.warn("Keyless request blocked", {canonicalLog: "keyless/consume",event: "keyless_exhausted",@@ -183,12 +240,14 @@ export async function keylessLimitBody(reason: "credits",mode,retryAfterSeconds,+ ...(prompt.signupRef ? { signupRef: prompt.signupRef } : {}),...keylessExhaustionTelemetry(ip ?? ""),});return {success: false,- error: KEYLESS_FREE_TIER_LIMIT_MESSAGE,+ error: prompt.error,reason: "credits",+ signup_url: prompt.signup_url,...(retryAfterSeconds ? { retry_after_seconds: retryAfterSeconds } : {}),};}diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.tsindex ec3253280..070be93d6 100644--- a/apps/api/src/routes/shared.ts+++ b/apps/api/src/routes/shared.ts@@ -320,6 +320,7 @@ export function authMiddleware(...(auth.retryAfterSeconds? { retry_after_seconds: auth.retryAfterSeconds }: {}),+ ...(auth.signupUrl ? { signup_url: auth.signupUrl } : {}),});} else {return;diff --git a/apps/api/src/types.ts b/apps/api/src/types.tsindex bf216cffc..4a72a6c68 100644--- a/apps/api/src/types.ts+++ b/apps/api/src/types.ts@@ -182,6 +182,8 @@ export type AuthResponse =// Machine-readable keyless quota details for trusted MCP recovery.keylessReason?: "requests" | "credits";retryAfterSeconds?: number;+ // Keyless prompts: the signup link in `error`, for clients that relay it.+ signupUrl?: string;};export enum NotificationType {